Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions scripts/integrations.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import './azure-openai-java.test.mjs';
import './langsmith-page.test.mjs';
import './vercel-platform-page.test.mjs';
import './scalekit-page.test.mjs';
import './trace-config-page.test.mjs';
import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
Expand Down
85 changes: 85 additions & 0 deletions scripts/trace-config-page.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { integrationAids } from '../src/lib/integrations.mjs';

const read = route => readFileSync(new URL(`../src/pages/docs/${route}.mdx`, import.meta.url), 'utf8');
const config = read('sdk/tracing/trace-config');
const environment = read('sdk/tracing/environment-variables');
const masking = read('sdk/tracing/mask-span-attributes');
const exceptions = read('sdk/tracing/add-events-exceptions-status');
const troubleshooting = read('observe/troubleshooting/missing-attributes');
const errors = config.split('## Errors and privacy')[1]?.split('## Cap attribute size')[0];

test('error privacy reference is discoverable and uses published core versions', () => {
assert.ok(integrationAids.some(aid => aid.href === '/docs/sdk/tracing/trace-config'));
assert.ok(errors, 'Keep the errors and privacy reference');
for (const page of [config, environment, masking]) {
assert.match(page, /`fi-instrumentation-otel` 1\.2\.3/);
assert.match(page, /`@traceai\/fi-core` 1\.1\.1/);
assert.doesNotMatch(page, /`fi-instrumentation-otel` 1\.2\.0\b/);
}
assert.doesNotMatch(errors, /must be published|next release|Fixes for them are being followed up|17 packages|Java and C# don't support it yet|same release/i);
});

test('error privacy retains failure classifications and removes known error text', () => {
for (const key of ['error.type', 'exception.type', 'exception.escaped']) {
const row = errors.split('\n').find(line => line.startsWith(`| \`${key}\``));
assert.ok(row, `Document ${key}`);
assert.match(row, /\| Kept(?: when set)? \|$/);
}
assert.match(errors, /\| Status code \| Span status \| `ERROR` \| `ERROR` \|/);
assert.match(errors, /\| Status description[^\n]*\| Empty \|/);
for (const key of ['exception.message', 'exception.stacktrace', 'error.message']) {
const row = errors.split('\n').find(line => line.startsWith(`| \`${key}\``));
assert.match(row ?? '', /\| Dropped \|$/);
}
for (const suffix of ['.exception.message', '.exception.stacktrace', '.error.message', '.error_message']) {
assert.ok(errors.includes(`\`${suffix}\``));
}
assert.match(errors, /module-qualified in Python, class name in TypeScript/);
assert.match(errors, /Output of a failed LangChain run[^\n]*\| Dropped \|/);
});

test('derived default uses only the six resolved content flags with explicit overrides', () => {
const defaults = errors.split('### Default')[1]?.split('### Scope')[0];
assert.ok(defaults);
for (const flag of ['hide_inputs', 'hide_outputs', 'hide_input_messages', 'hide_output_messages', 'hide_input_text', 'hide_output_text']) {
assert.ok(defaults.includes(`\`${flag}\``));
assert.ok(environment.includes(`\`${flag}\``));
}
assert.match(defaults, /Off otherwise/);
assert.match(defaults, /`hide_input_images`, `hide_embedding_vectors`, `hide_llm_invocation_parameters`, and `pii_redaction` don't affect it/);
assert.match(defaults, /value set in code takes precedence over the environment variable/);
assert.match(defaults, /`False` or `FI_HIDE_ERROR_DETAILS=false`[^\n]*Off, even when content is hidden/);
assert.match(environment, /explicit environment value takes precedence over the derived default/);
assert.match(troubleshooting, /image-only masking does not enable it/);
});

test('privacy scope does not promise exporter-wide filtering or retain obsolete exclusions', () => {
assert.match(errors, /not an exporter-wide filter/);
assert.match(errors, /plain OpenTelemetry tracer is not filtered/);
assert.match(errors, /Native integrations have their own content controls/);
assert.match(errors, /redaction in an OpenTelemetry Collector/);
assert.match(errors, /`traceai-chromadb` 0\.2\.0 use this wrapper/);
assert.doesNotMatch(errors, /These instrumentors bypass|Python: a2a|TypeScript: `@traceai\/llamaindex`/);
assert.match(masking, /not an exporter-wide filter/);
assert.doesNotMatch(masking, /accepted by all traceAI auto-instrumentors|apply globally to all instrumentors/);
assert.match(exceptions, /Plain OpenTelemetry spans are not filtered/);
});

test('examples hide error details and diagnostics use a maintained exporter', () => {
const examples = errors.split('### Example')[1];
assert.ok(examples);
assert.match(examples, /hide_error_details=True/);
assert.match(examples, /hideErrorDetails: true/);
assert.match(examples, /export FI_HIDE_ERROR_DETAILS=true/);
assert.doesNotMatch(examples, /hide_error_details=False|hideErrorDetails: false|export FI_HIDE_ERROR_DETAILS=false/);
assert.match(errors, /Error messages can expose prompts and other sensitive data/);
for (const page of [environment, masking, exceptions, troubleshooting]) {
assert.ok(page.includes('/docs/sdk/tracing/trace-config#errors-and-privacy'));
}
assert.match(troubleshooting, /SimpleSpanProcessor\(ConsoleSpanExporter\(\)\)/);
assert.match(troubleshooting, /Use synthetic data/);
assert.doesNotMatch(troubleshooting, /class PrintAttributes/);
});
1 change: 1 addition & 0 deletions src/lib/integrations.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -165,6 +165,7 @@ export const integrationAids = [
{ name: 'Hook-to-OTLP emitter', href: '/docs/integrations/coding-agents/hook-to-otlp', category: 'coding' },
{ name: 'OpenAI Assistants retirement', href: '/docs/integrations/traceai/openai_assistants', category: 'providers' },
{ name: 'traceAI setup', href: '/docs/integrations/traceai' },
{ name: 'Trace privacy settings', href: '/docs/sdk/tracing/trace-config' },
{ name: 'Java SDK setup', href: '/docs/integrations/traceai/java', category: 'java' },
];

Expand Down
12 changes: 4 additions & 8 deletions src/pages/docs/observe/troubleshooting/missing-attributes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -54,24 +54,20 @@ The trace shows up, but it's incomplete — a nested span is missing, or fields
| Cause | What you see | Fix |
|---|---|---|
| Redaction is on (check first) | Input/output render as hidden or blank, but the span is otherwise complete | Confirm whether `FI_HIDE_INPUTS` / `FI_HIDE_OUTPUTS` or `TraceConfig` masking is set — if so, the blank is expected. See [Mask span attributes](/docs/sdk/tracing/mask-span-attributes). |
| Error details hidden | A failed traceAI span shows `ERROR` and `error.type` but no status description, exception message, or stack trace | Check `hide_error_details` (Python), `hideErrorDetails` (TypeScript), and `FI_HIDE_ERROR_DETAILS`. The default is on when an input/output value, message, or text hiding flag is true; image-only masking does not enable it. Retain error text only if it is safe to export, since it can expose hidden content. See [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy) for the override and precedence rules. |
| Instrumentor not attached for that framework | A framework's child spans (e.g. nested LangGraph nodes) never appear | Install and `instrument()` the instrumentor for the missing framework, attached to the provider. |
| Attribute set on the wrong span / after close | A custom attribute you set isn't on the span | Set attributes while the span is active; a value set after the `with` block closes is dropped. |
| Custom key isn't indexed for filtering | The attribute is on the span but you can't filter by it | Use a [semantic-convention](/docs/sdk/tracing/semantic-conventions) key where one exists — the UI filters on standard keys. |
| Unsupported value type | The attribute is silently dropped | Attribute values must be string, bool, int, float, or an array of those. |

## Diagnostic commands

Print one span's attributes from a span exporter to confirm what actually reached the SDK, so you can tell a redacted field from a missing one:
Inspect exported spans with OpenTelemetry's console exporter to distinguish a redacted field from a missing one. Use synthetic data: this prints span attributes and events to your application logs. Attach it to your existing provider before running the request, and remove it after debugging.

```python
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, SpanExporter
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

class PrintAttributes(SpanExporter):
def export(self, spans):
for span in spans:
print(span.name, dict(span.attributes))

trace_provider.add_span_processor(SimpleSpanProcessor(PrintAttributes()))
trace_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
```

If the attribute prints here but isn't filterable in the UI, the key isn't indexed; if it doesn't print at all, it was set on the wrong span or after close.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,7 @@ Spans capture timing and attributes, but they do not automatically record what h
- **`add_event()` / `addEvent()`**:Attaches a timestamped message to the span at the moment it's called. Useful for logging discrete actions without creating a new span.
- **`set_status()` / `setStatus()`**:Sets the span's status to `OK` or `ERROR`. An `ERROR` status with a message surfaces the failure in trace UIs and alerting.
- **`record_exception()` / `recordException()`**:Attaches full exception details (type, message, stack trace) as a span event. Always pair with `set_status(ERROR)` for complete failure context.
- **Error details and masking**: On spans created through the Python or TypeScript traceAI wrapper, `hide_error_details` (`hideErrorDetails` in TypeScript) decides whether the status description, exception message, and stack trace are kept. It's on by default when you hide inputs or outputs, so a failed span keeps its `ERROR` status and exception type but not the text. Plain OpenTelemetry spans are not filtered by this setting. See [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy).
- **`is_recording()`**:Guards against no-op spans. Always check before setting attributes or events on a span retrieved from `get_current_span()`.

---
Expand Down
5 changes: 4 additions & 1 deletion src/pages/docs/sdk/tracing/environment-variables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: "Environment variables that configure traceAI tracing."
---


All languages read from the same set of environment variables:
traceAI SDKs share the following environment-variable names. Support varies by SDK and integration; native OpenTelemetry integrations use the controls documented in their integration guide.

| Variable | Purpose | Default |
|----------|---------|---------|
Expand All @@ -25,4 +25,7 @@ All languages read from the same set of environment variables:
| `FI_HIDE_LLM_INVOCATION_PARAMETERS` | Redact model parameters | False |
| `FI_BASE64_IMAGE_MAX_LENGTH` | Max base64 image chars | 32000 |
| `FI_PII_REDACTION` | Auto-mask PII (Python) | False |
| `FI_HIDE_ERROR_DETAILS` | Hide error messages and stack traces on supported traceAI spans. Use Python `fi-instrumentation-otel` 1.2.3 or later or TypeScript `@traceai/fi-core` 1.1.1 or later. See [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy) | When unset, derived from the resolved input/output content flags in code or the environment; see below |

For Python and TypeScript, `FI_HIDE_ERROR_DETAILS` defaults to true when any of `hide_inputs`, `hide_outputs`, `hide_input_messages`, `hide_output_messages`, `hide_input_text`, or `hide_output_text` is true (camelCase in TypeScript). These flags can come from code or their `FI_` environment variables. Otherwise, it defaults to false. Image-only, embedding-vector, invocation-parameter, and PII masking do not enable it. An explicit error-details setting in code takes precedence over `FI_HIDE_ERROR_DETAILS`; an explicit environment value takes precedence over the derived default.

13 changes: 8 additions & 5 deletions src/pages/docs/sdk/tracing/mask-span-attributes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: "Redact sensitive inputs, outputs, images, and embeddings from span

## About

Traces often contain sensitive data: user messages, API responses, PII, or large base64-encoded images. Sending all of this to a trace backend creates privacy and compliance problems. Masking span attributes removes this data before it leaves the application: it only truncates for one field, `base64_image_max_length`, which caps the length of base64-encoded images. Everything else is either sent in full or hidden completely; there is no general truncation. To cap the size of arbitrary attribute values (large prompts, tool outputs), see [Cap attribute size](/docs/sdk/tracing/trace-config#cap-attribute-size) instead. Configuration is available at two levels: environment variables for global defaults across all instrumentors, and `TraceConfig` in code for per-instrumentor control.
Traces often contain sensitive data: user messages, API responses, PII, or large base64-encoded images. Sending all of this to a trace backend creates privacy and compliance problems. Masking span attributes removes this data before it leaves the application: it only truncates for one field, `base64_image_max_length`, which caps the length of base64-encoded images. Everything else is either sent in full or hidden completely; there is no general truncation. To cap the size of arbitrary attribute values (large prompts, tool outputs), see [Cap attribute size](/docs/sdk/tracing/trace-config#cap-attribute-size) instead. Configuration is available at two levels: environment variables for defaults across instrumentors that support `TraceConfig`, and `TraceConfig` in code for per-instrumentor control. These settings are not an exporter-wide filter for native OpenTelemetry spans; follow the integration's own privacy instructions.

---

Expand All @@ -14,6 +14,7 @@ Traces often contain sensitive data: user messages, API responses, PII, or large
- **Privacy and compliance**: Hide user inputs and LLM outputs to prevent sensitive data from being stored in trace backends.
- **Image redaction**: Suppress base64-encoded images from input messages or cap their length to reduce payload size.
- **Selective masking**: Hide only specific parts of a span (e.g. input text but not output messages) while keeping the rest visible.
- **Error text**: A provider error body can quote your prompt back, and a framework error can include a traceback with local file paths. Hiding inputs or outputs hides error details too; see [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy) to keep or drop them independently.
- **Environment-specific config**: Use environment variables for deployment-level defaults and `TraceConfig` in code for per-instrumentor overrides.

---
Expand All @@ -22,7 +23,7 @@ Traces often contain sensitive data: user messages, API responses, PII, or large

<Tabs>
<Tab title="Environment Variables">
These apply globally to all instrumentors at startup.
Set these before initializing instrumentors that support `TraceConfig`. An explicit value in code takes precedence.

| Environment Variable | Description | Type | Default |
|----------------------|-------------|------|---------|
Expand All @@ -35,10 +36,11 @@ Traces often contain sensitive data: user messages, API responses, PII, or large
| `FI_HIDE_OUTPUT_TEXT` | Hides text from output messages | bool | False |
| `FI_HIDE_EMBEDDING_VECTORS` | Hides returned embedding vectors | bool | False |
| `FI_BASE64_IMAGE_MAX_LENGTH` | Caps the character count of a base64 encoded image | int | 32,000 |
| `FI_HIDE_ERROR_DETAILS` | Hides the status description, exception message, and stack trace on supported traceAI spans. Use Python `fi-instrumentation-otel` 1.2.3 or later or TypeScript `@traceai/fi-core` 1.1.1 or later | bool | When unset, derived from the resolved input/output content flags in code or the environment; see [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy) |
</Tab>

<Tab title="TraceConfig in Code">
Pass a `TraceConfig` object to any auto-instrumentor for per-instrumentor control. Values set here take precedence over environment variables.
Pass a `TraceConfig` object to an instrumentor that supports it, such as the OpenAI instrumentors below, for per-instrumentor control. Values set here take precedence over environment variables.

<CodeGroup>

Expand Down Expand Up @@ -90,11 +92,12 @@ Traces often contain sensitive data: user messages, API responses, PII, or large

## Key concepts

- **`TraceConfig`**:An object accepted by all traceAI auto-instrumentors. Use it to specify masking settings directly in code, scoped to a single instrumentor.
- **Environment variables**:Global defaults applied to all instrumentors. Useful for deployment-level configuration without changing code.
- **`TraceConfig`**: An object accepted by supporting traceAI instrumentors. Use it to specify masking settings directly in code, scoped to a single instrumentor.
- **Environment variables**: Defaults shared by instrumentors that support these settings. Useful for deployment-level configuration without changing code.
- **Precedence order**:`TraceConfig` in code → environment variables → default values. More specific settings always win.
- **`hide_inputs` / `hide_outputs`**:Broad flags that hide all input/output values and messages in one setting.
- **`base64_image_max_length`**:Caps the logged length of base64-encoded images. Default is 32,000 characters.
- **`hide_error_details`**: Drops the status description, exception message, and stack trace from failed spans while keeping the `ERROR` status, `error.type`, and `exception.type`. On by default when `hide_inputs`, `hide_outputs`, or an input/output message or text hiding flag is true. Image-only masking does not enable it. See [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy).

---

Expand Down
Loading
Loading