From 56224da9bfc4603281b8d38d3ce9a36c773f84e8 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Sun, 18 Oct 2026 18:48:32 -0700 Subject: [PATCH 1/4] docs(tracing): document FI_HIDE_ERROR_DETAILS and errors and privacy Add the hide_error_details TraceConfig field and FI_HIDE_ERROR_DETAILS env var: what it keeps (ERROR status, error.type, exception.type) and drops (status description, exception.message, exception.stacktrace, error.message, provider error-body attributes), the derived default from the content hide_* flags, the behaviour change for existing users of those flags, and Python/TypeScript/env examples. Marked as available from the fi-instrumentation-otel next release. Cross-link it from the env var reference, mask span attributes, events/exceptions/status, and the missing-attributes troubleshooting page. Co-Authored-By: Claude Opus 5.5 --- .../troubleshooting/missing-attributes.mdx | 1 + .../tracing/add-events-exceptions-status.mdx | 1 + .../sdk/tracing/environment-variables.mdx | 1 + .../docs/sdk/tracing/mask-span-attributes.mdx | 3 + src/pages/docs/sdk/tracing/trace-config.mdx | 110 +++++++++++++++++- 5 files changed, 115 insertions(+), 1 deletion(-) diff --git a/src/pages/docs/observe/troubleshooting/missing-attributes.mdx b/src/pages/docs/observe/troubleshooting/missing-attributes.mdx index 51eac4288..8de10f430 100644 --- a/src/pages/docs/observe/troubleshooting/missing-attributes.mdx +++ b/src/pages/docs/observe/troubleshooting/missing-attributes.mdx @@ -54,6 +54,7 @@ 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 span shows `ERROR` and `error.type` but no status description, exception message, or stack trace | `hide_error_details` is on. It's on by default when any input or output `hide_*` field is set. To keep error text, set `hide_error_details=False` or `FI_HIDE_ERROR_DETAILS=false`. See [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy). | | 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. | diff --git a/src/pages/docs/sdk/tracing/add-events-exceptions-status.mdx b/src/pages/docs/sdk/tracing/add-events-exceptions-status.mdx index 2aa3e9603..b1f637176 100644 --- a/src/pages/docs/sdk/tracing/add-events-exceptions-status.mdx +++ b/src/pages/docs/sdk/tracing/add-events-exceptions-status.mdx @@ -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 traceAI creates, `hide_error_details` 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. 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()`. --- diff --git a/src/pages/docs/sdk/tracing/environment-variables.mdx b/src/pages/docs/sdk/tracing/environment-variables.mdx index 76cdb75a9..3a17b620b 100644 --- a/src/pages/docs/sdk/tracing/environment-variables.mdx +++ b/src/pages/docs/sdk/tracing/environment-variables.mdx @@ -25,4 +25,5 @@ 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 failed spans (Python and TypeScript, next traceAI release). See [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy) | Derived: true when any of `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS`, `FI_HIDE_INPUT_MESSAGES`, `FI_HIDE_OUTPUT_MESSAGES`, `FI_HIDE_INPUT_TEXT`, or `FI_HIDE_OUTPUT_TEXT` is true, otherwise False | diff --git a/src/pages/docs/sdk/tracing/mask-span-attributes.mdx b/src/pages/docs/sdk/tracing/mask-span-attributes.mdx index 0ed8d38d4..f31b1d547 100644 --- a/src/pages/docs/sdk/tracing/mask-span-attributes.mdx +++ b/src/pages/docs/sdk/tracing/mask-span-attributes.mdx @@ -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. --- @@ -35,6 +36,7 @@ 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 failed spans. Python and TypeScript, next traceAI release | bool | Derived: true when `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS`, `FI_HIDE_INPUT_MESSAGES`, `FI_HIDE_OUTPUT_MESSAGES`, `FI_HIDE_INPUT_TEXT`, or `FI_HIDE_OUTPUT_TEXT` is true | @@ -95,6 +97,7 @@ Traces often contain sensitive data: user messages, API responses, PII, or large - **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 any input or output message or text field is set. See [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy). --- diff --git a/src/pages/docs/sdk/tracing/trace-config.mdx b/src/pages/docs/sdk/tracing/trace-config.mdx index ae92a8e71..b4dd2bec7 100644 --- a/src/pages/docs/sdk/tracing/trace-config.mdx +++ b/src/pages/docs/sdk/tracing/trace-config.mdx @@ -92,8 +92,116 @@ Control what data gets captured. Useful for privacy compliance, reducing payload | `hide_llm_invocation_parameters` | bool | False | Model parameters (temperature, etc.) | | `base64_image_max_length` | int | 32000 | Truncate base64 images beyond this length | | `pii_redaction` | bool | False | Automatically mask PII (Python only) | +| `hide_error_details` | bool | Derived | Error messages and stack traces on failed spans (Python and TypeScript). See [Errors and privacy](#errors-and-privacy) | -Each field maps to an environment variable with the `FI_` prefix (e.g. `hide_inputs` -> `FI_HIDE_INPUTS`). +Each field maps to an environment variable with the `FI_` prefix (e.g. `hide_inputs` -> `FI_HIDE_INPUTS`, `hide_error_details` -> `FI_HIDE_ERROR_DETAILS`). + +## Errors and privacy + + +Available from the next traceAI release: the `fi-instrumentation-otel` next release for Python, and the matching `@traceai/fi-core` release for TypeScript, where the field is `hideErrorDetails`. Java and C# don't support `hide_error_details` or `FI_HIDE_ERROR_DETAILS` yet. + + +When a call fails, traceAI marks the span `ERROR` and records the exception. Error text can carry the same data you hid with the other `hide_*` fields: a provider error body can quote your prompt back or include provider and gateway request IDs, and a framework error can include a stack trace with local file paths. `hide_error_details` keeps the fact that a span failed and what kind of failure it was, and drops the text. + +| Field | Where it lives | `hide_error_details` off | `hide_error_details` on | +|-------|----------------|--------------------------|-------------------------| +| Status code | Span status | `ERROR` | `ERROR` | +| Status description | Span status | The exception message, never a traceback | Empty | +| `error.type` | Span attribute | The provider's error code when the SDK exposes one, otherwise the fully qualified exception class (e.g. `billing.errors.PaymentDeclined`) | Kept | +| `exception.type` | `exception` event | The exception class | Kept | +| `exception.escaped` | `exception` event | Kept when set | Kept when set | +| `exception.message` | `exception` event | Kept | Dropped | +| `exception.stacktrace` | `exception` event | Kept | Dropped | +| `error.message` | Span attribute | Kept | Dropped | +| Provider error-body attributes | Span attributes | Kept | Dropped | + +The status description never carries a traceback, whatever the setting. LangChain spans used to put the full traceback there; the stack trace now lives only in `exception.stacktrace` on the exception event. + +### Default + +You rarely need to set `hide_error_details` yourself. When you don't set it in code or through `FI_HIDE_ERROR_DETAILS`, traceAI derives it from the content fields: + +| `hide_error_details` setting | Result | +|------------------------------|--------| +| Not set | On if any of `hide_inputs`, `hide_outputs`, `hide_input_messages`, `hide_output_messages`, `hide_input_text`, or `hide_output_text` is true. Off otherwise. | +| `True` or `FI_HIDE_ERROR_DETAILS=true` | On, whatever the other fields are | +| `False` or `FI_HIDE_ERROR_DETAILS=false` | Off, even when content is hidden | + +The content fields count whether you set them in code or through their own environment variables, so `FI_HIDE_INPUTS=true` on its own also hides error details. `hide_input_images`, `hide_embedding_vectors`, `hide_llm_invocation_parameters`, and `pii_redaction` don't affect it. As with the other fields, a value set in code takes precedence over the environment variable. + + +This is a behaviour change if you already hide content. After you upgrade, setting any of the content fields above also hides error details: failed spans keep their `ERROR` status, `error.type`, and `exception.type`, but lose the status description, exception message, and stack trace. Set `hide_error_details=False` (or `FI_HIDE_ERROR_DETAILS=false`) to keep them. + + +`hide_error_details` applies to spans that traceAI creates: spans from auto-instrumentors and spans started through `FITracer`, including an exception recorded automatically when it escapes a span's context manager. A span you start with a plain OpenTelemetry tracer isn't filtered. + +### Example + +Hide inputs and outputs but keep error messages and stack traces for debugging: + + + + ```python + from fi_instrumentation import register, TraceConfig + from fi_instrumentation.fi_types import ProjectType + from traceai_openai import OpenAIInstrumentor + + trace_provider = register( + project_name="my-chatbot", + project_type=ProjectType.OBSERVE, + ) + + config = TraceConfig( + hide_inputs=True, + hide_outputs=True, + # Without this line, hide_inputs would also hide error details + hide_error_details=False, + ) + + OpenAIInstrumentor().instrument( + tracer_provider=trace_provider, + config=config, + ) + ``` + + + ```typescript + import { register, ProjectType } from "@traceai/fi-core"; + import { OpenAIInstrumentation } from "@traceai/openai"; + import { registerInstrumentations } from "@opentelemetry/instrumentation"; + + const tracerProvider = register({ + projectName: "my-chatbot", + projectType: ProjectType.OBSERVE, + }); + + registerInstrumentations({ + tracerProvider, + instrumentations: [ + new OpenAIInstrumentation({ + traceConfig: { + hideInputs: true, + hideOutputs: true, + // Without this line, hideInputs would also hide error details + hideErrorDetails: false, + }, + }), + ], + }); + ``` + + + ```bash + export FI_HIDE_INPUTS=true + export FI_HIDE_OUTPUTS=true + # Without this line, FI_HIDE_INPUTS would also hide error details + export FI_HIDE_ERROR_DETAILS=false + ``` + + + +To hide error details while still capturing content, set `hide_error_details=True` (or `FI_HIDE_ERROR_DETAILS=true`) on its own. ## Cap attribute size From 54efa3e7cf76036c98b9ac66cea2217f276937b7 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Mon, 19 Oct 2026 03:47:45 -0700 Subject: [PATCH 2/4] docs(tracing): sync hide-error-details with traceAI#272 and #271 final code Co-Authored-By: Claude Opus 5.5 --- .../sdk/tracing/environment-variables.mdx | 2 +- .../docs/sdk/tracing/mask-span-attributes.mdx | 2 +- src/pages/docs/sdk/tracing/trace-config.mdx | 25 ++++++++++++++++--- 3 files changed, 24 insertions(+), 5 deletions(-) diff --git a/src/pages/docs/sdk/tracing/environment-variables.mdx b/src/pages/docs/sdk/tracing/environment-variables.mdx index 3a17b620b..d522c9946 100644 --- a/src/pages/docs/sdk/tracing/environment-variables.mdx +++ b/src/pages/docs/sdk/tracing/environment-variables.mdx @@ -25,5 +25,5 @@ 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 failed spans (Python and TypeScript, next traceAI release). See [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy) | Derived: true when any of `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS`, `FI_HIDE_INPUT_MESSAGES`, `FI_HIDE_OUTPUT_MESSAGES`, `FI_HIDE_INPUT_TEXT`, or `FI_HIDE_OUTPUT_TEXT` is true, otherwise False | +| `FI_HIDE_ERROR_DETAILS` | Hide error messages and stack traces on failed spans (Python `fi-instrumentation-otel` 1.2.0, TypeScript `@traceai/fi-core` 1.1.0). See [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy) | Derived: true when any of `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS`, `FI_HIDE_INPUT_MESSAGES`, `FI_HIDE_OUTPUT_MESSAGES`, `FI_HIDE_INPUT_TEXT`, or `FI_HIDE_OUTPUT_TEXT` is true, otherwise False | diff --git a/src/pages/docs/sdk/tracing/mask-span-attributes.mdx b/src/pages/docs/sdk/tracing/mask-span-attributes.mdx index f31b1d547..c026c6464 100644 --- a/src/pages/docs/sdk/tracing/mask-span-attributes.mdx +++ b/src/pages/docs/sdk/tracing/mask-span-attributes.mdx @@ -36,7 +36,7 @@ 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 failed spans. Python and TypeScript, next traceAI release | bool | Derived: true when `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS`, `FI_HIDE_INPUT_MESSAGES`, `FI_HIDE_OUTPUT_MESSAGES`, `FI_HIDE_INPUT_TEXT`, or `FI_HIDE_OUTPUT_TEXT` is true | + | `FI_HIDE_ERROR_DETAILS` | Hides the status description, exception message, and stack trace on failed spans. Python `fi-instrumentation-otel` 1.2.0, TypeScript `@traceai/fi-core` 1.1.0 | bool | Derived: true when `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS`, `FI_HIDE_INPUT_MESSAGES`, `FI_HIDE_OUTPUT_MESSAGES`, `FI_HIDE_INPUT_TEXT`, or `FI_HIDE_OUTPUT_TEXT` is true | diff --git a/src/pages/docs/sdk/tracing/trace-config.mdx b/src/pages/docs/sdk/tracing/trace-config.mdx index b4dd2bec7..60d0360f8 100644 --- a/src/pages/docs/sdk/tracing/trace-config.mdx +++ b/src/pages/docs/sdk/tracing/trace-config.mdx @@ -99,7 +99,7 @@ Each field maps to an environment variable with the `FI_` prefix (e.g. `hide_inp ## Errors and privacy -Available from the next traceAI release: the `fi-instrumentation-otel` next release for Python, and the matching `@traceai/fi-core` release for TypeScript, where the field is `hideErrorDetails`. Java and C# don't support `hide_error_details` or `FI_HIDE_ERROR_DETAILS` yet. +Available in `fi-instrumentation-otel` 1.2.0 (Python, option `hide_error_details`, env var `FI_HIDE_ERROR_DETAILS`) and `@traceai/fi-core` 1.1.0 (TypeScript, option `hideErrorDetails`, same env var). The instrumentation packages must be published after fi-core to pick it up: in Python `traceai-langchain` 0.2.1 and `traceai-autogen` 0.2.1; in TypeScript `@traceai/openai` 0.1.14, `@traceai/anthropic` 0.1.3, `@traceai/bedrock` 0.1.1 and `@traceai/langchain` 0.1.3. Java and C# don't support it yet. When a call fails, traceAI marks the span `ERROR` and records the exception. Error text can carry the same data you hid with the other `hide_*` fields: a provider error body can quote your prompt back or include provider and gateway request IDs, and a framework error can include a stack trace with local file paths. `hide_error_details` keeps the fact that a span failed and what kind of failure it was, and drops the text. @@ -108,7 +108,7 @@ When a call fails, traceAI marks the span `ERROR` and records the exception. Err |-------|----------------|--------------------------|-------------------------| | Status code | Span status | `ERROR` | `ERROR` | | Status description | Span status | The exception message, never a traceback | Empty | -| `error.type` | Span attribute | The provider's error code when the SDK exposes one, otherwise the fully qualified exception class (e.g. `billing.errors.PaymentDeclined`) | Kept | +| `error.type` | Span attribute | The provider's error code when the SDK exposes one, otherwise the fully qualified exception class (e.g. `billing.errors.PaymentDeclined`), otherwise `_OTHER` | Kept | | `exception.type` | `exception` event | The exception class | Kept | | `exception.escaped` | `exception` event | Kept when set | Kept when set | | `exception.message` | `exception` event | Kept | Dropped | @@ -134,7 +134,26 @@ The content fields count whether you set them in code or through their own envir This is a behaviour change if you already hide content. After you upgrade, setting any of the content fields above also hides error details: failed spans keep their `ERROR` status, `error.type`, and `exception.type`, but lose the status description, exception message, and stack trace. Set `hide_error_details=False` (or `FI_HIDE_ERROR_DETAILS=false`) to keep them. -`hide_error_details` applies to spans that traceAI creates: spans from auto-instrumentors and spans started through `FITracer`, including an exception recorded automatically when it escapes a span's context manager. A span you start with a plain OpenTelemetry tracer isn't filtered. +`hide_error_details` applies to spans created through the shared traceAI wrapper (`FiSpan` / `FITracer`): spans from the instrumentors that use it, spans you start through `FITracer`, and an exception recorded automatically when it escapes a span's context manager. A span you start with a plain OpenTelemetry tracer isn't filtered. + + +These instrumentors bypass the shared wrapper, so neither the content `hide_*` fields nor `hide_error_details` apply to their spans yet. Fixes for them are being followed up. + +- Python: a2a, beeai, strands, claude-agent-sdk, pydantic-ai, agno, pipecat, mcp, and the vector stores chromadb, lancedb, milvus, mongodb-vector, pgvector, pinecone, qdrant, redis-vector and weaviate (17 packages), plus livekit. +- TypeScript: `@traceai/llamaindex`, `@traceai/vercel` and `@traceai/mastra`. + + +### Content-hiding fixes in the same release + +These are privacy fixes for anyone who already uses `FI_HIDE_*`: + +- `hide_inputs` / `hideInputs` now also redacts `raw.input` and the prompt-template variables (`llm.prompt_template.variables` / `gen_ai.prompt.template.variables`). `hide_outputs` / `hideOutputs` now also redacts `raw.output`. +- TypeScript now masks the attributes passed when a span is created (`startSpan` and `startActiveSpan`), and link attributes. Before, `FI_HIDE_INPUTS` did not mask prompts that instrumentors set at creation, which affected about 22 TypeScript instrumentors, `@traceai/openai` included. Every published `@traceai/fi-core` release up to 1.0.0 has this gap. + +### Behaviour changes (TypeScript) + +- `FI_HIDE_*` environment variables now apply even when no `traceConfig` is passed. +- Inside `FITracer.startActiveSpan`, the active span is now the `FISpan`, not the SDK span. Code that casts it to the SDK `Span` breaks there. ### Example From 41950e601cb10cb0e711b9bd22d4bbb0575df464 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Wed, 21 Oct 2026 16:37:01 -0700 Subject: [PATCH 3/4] docs(tracing): name the exact error-text keys hide_error_details drops The 'Provider error-body attributes' row was vaguer than the code. traceAI#272 and #271 drop keys ending in .exception.message, .exception.stacktrace, .error.message and .error_message, and Python LangChain drops a failed run's outputs (langchain-core fills them with the provider error response). Co-Authored-By: Claude Opus 5.5 --- src/pages/docs/sdk/tracing/trace-config.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/pages/docs/sdk/tracing/trace-config.mdx b/src/pages/docs/sdk/tracing/trace-config.mdx index 60d0360f8..8e77825fe 100644 --- a/src/pages/docs/sdk/tracing/trace-config.mdx +++ b/src/pages/docs/sdk/tracing/trace-config.mdx @@ -114,7 +114,8 @@ When a call fails, traceAI marks the span `ERROR` and records the exception. Err | `exception.message` | `exception` event | Kept | Dropped | | `exception.stacktrace` | `exception` event | Kept | Dropped | | `error.message` | Span attribute | Kept | Dropped | -| Provider error-body attributes | Span attributes | Kept | Dropped | +| Other error-text attributes: any key ending in `.exception.message`, `.exception.stacktrace`, `.error.message` or `.error_message` (for example `autogen.error.message`) | Span attributes | Kept | Dropped | +| Output of a failed LangChain run (Python) | Span attributes | Kept. langchain-core fills it with the provider's error response | Dropped | The status description never carries a traceback, whatever the setting. LangChain spans used to put the full traceback there; the stack trace now lives only in `exception.stacktrace` on the exception event. From 4ca7a5b71d517342c91b96310035ee51da4a1402 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Thu, 5 Nov 2026 22:09:07 -0800 Subject: [PATCH 4/4] docs(tracing): align error privacy guidance with released SDKs Use available Python and TypeScript core versions, replace the stale instrumentor exclusion list with the actual wrapper and native-tracing boundary, and keep debugging overrides privacy-conscious. Register the reference as a setup aid and cover its semantics with page-contract checks. Co-Authored-By: Claude Code --- scripts/integrations.test.mjs | 1 + scripts/trace-config-page.test.mjs | 85 +++++++++++++++++++ src/lib/integrations.mjs | 1 + .../troubleshooting/missing-attributes.mdx | 13 +-- .../tracing/add-events-exceptions-status.mdx | 2 +- .../sdk/tracing/environment-variables.mdx | 6 +- .../docs/sdk/tracing/mask-span-attributes.mdx | 14 +-- src/pages/docs/sdk/tracing/trace-config.mdx | 57 ++++++------- 8 files changed, 128 insertions(+), 51 deletions(-) create mode 100644 scripts/trace-config-page.test.mjs diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index 30ff909ed..cb5b4da93 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -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'; diff --git a/scripts/trace-config-page.test.mjs b/scripts/trace-config-page.test.mjs new file mode 100644 index 000000000..a3be2485a --- /dev/null +++ b/scripts/trace-config-page.test.mjs @@ -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/); +}); diff --git a/src/lib/integrations.mjs b/src/lib/integrations.mjs index df0f390a2..5fa872d73 100644 --- a/src/lib/integrations.mjs +++ b/src/lib/integrations.mjs @@ -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' }, ]; diff --git a/src/pages/docs/observe/troubleshooting/missing-attributes.mdx b/src/pages/docs/observe/troubleshooting/missing-attributes.mdx index 8de10f430..d2b41d978 100644 --- a/src/pages/docs/observe/troubleshooting/missing-attributes.mdx +++ b/src/pages/docs/observe/troubleshooting/missing-attributes.mdx @@ -54,7 +54,7 @@ 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 span shows `ERROR` and `error.type` but no status description, exception message, or stack trace | `hide_error_details` is on. It's on by default when any input or output `hide_*` field is set. To keep error text, set `hide_error_details=False` or `FI_HIDE_ERROR_DETAILS=false`. See [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy). | +| 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. | @@ -62,17 +62,12 @@ The trace shows up, but it's incomplete — a nested span is missing, or fields ## 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. diff --git a/src/pages/docs/sdk/tracing/add-events-exceptions-status.mdx b/src/pages/docs/sdk/tracing/add-events-exceptions-status.mdx index b1f637176..baf1c0b83 100644 --- a/src/pages/docs/sdk/tracing/add-events-exceptions-status.mdx +++ b/src/pages/docs/sdk/tracing/add-events-exceptions-status.mdx @@ -162,7 +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 traceAI creates, `hide_error_details` 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. See [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy). +- **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()`. --- diff --git a/src/pages/docs/sdk/tracing/environment-variables.mdx b/src/pages/docs/sdk/tracing/environment-variables.mdx index d522c9946..867a13a43 100644 --- a/src/pages/docs/sdk/tracing/environment-variables.mdx +++ b/src/pages/docs/sdk/tracing/environment-variables.mdx @@ -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 | |----------|---------|---------| @@ -25,5 +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 failed spans (Python `fi-instrumentation-otel` 1.2.0, TypeScript `@traceai/fi-core` 1.1.0). See [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy) | Derived: true when any of `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS`, `FI_HIDE_INPUT_MESSAGES`, `FI_HIDE_OUTPUT_MESSAGES`, `FI_HIDE_INPUT_TEXT`, or `FI_HIDE_OUTPUT_TEXT` is true, otherwise 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. diff --git a/src/pages/docs/sdk/tracing/mask-span-attributes.mdx b/src/pages/docs/sdk/tracing/mask-span-attributes.mdx index c026c6464..42f9e41dc 100644 --- a/src/pages/docs/sdk/tracing/mask-span-attributes.mdx +++ b/src/pages/docs/sdk/tracing/mask-span-attributes.mdx @@ -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. --- @@ -23,7 +23,7 @@ Traces often contain sensitive data: user messages, API responses, PII, or large - 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 | |----------------------|-------------|------|---------| @@ -36,11 +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 failed spans. Python `fi-instrumentation-otel` 1.2.0, TypeScript `@traceai/fi-core` 1.1.0 | bool | Derived: true when `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS`, `FI_HIDE_INPUT_MESSAGES`, `FI_HIDE_OUTPUT_MESSAGES`, `FI_HIDE_INPUT_TEXT`, or `FI_HIDE_OUTPUT_TEXT` is true | + | `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) | - 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. @@ -92,12 +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 any input or output message or text field is set. See [Errors and privacy](/docs/sdk/tracing/trace-config#errors-and-privacy). +- **`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). --- diff --git a/src/pages/docs/sdk/tracing/trace-config.mdx b/src/pages/docs/sdk/tracing/trace-config.mdx index 8e77825fe..8bc2ece77 100644 --- a/src/pages/docs/sdk/tracing/trace-config.mdx +++ b/src/pages/docs/sdk/tracing/trace-config.mdx @@ -99,7 +99,9 @@ Each field maps to an environment variable with the `FI_` prefix (e.g. `hide_inp ## Errors and privacy -Available in `fi-instrumentation-otel` 1.2.0 (Python, option `hide_error_details`, env var `FI_HIDE_ERROR_DETAILS`) and `@traceai/fi-core` 1.1.0 (TypeScript, option `hideErrorDetails`, same env var). The instrumentation packages must be published after fi-core to pick it up: in Python `traceai-langchain` 0.2.1 and `traceai-autogen` 0.2.1; in TypeScript `@traceai/openai` 0.1.14, `@traceai/anthropic` 0.1.3, `@traceai/bedrock` 0.1.1 and `@traceai/langchain` 0.1.3. Java and C# don't support it yet. +For the Python and TypeScript settings below, use `fi-instrumentation-otel` 1.2.3 or later (Python, `hide_error_details`) or `@traceai/fi-core` 1.1.1 or later (TypeScript, `hideErrorDetails`). Both read `FI_HIDE_ERROR_DETAILS`. + +Upgrade the instrumentor as well as the core package. For Python LangChain and AutoGen, use `traceai-langchain` 0.2.1 or later and `traceai-autogen` 0.2.1 or later. For TypeScript, use `@traceai/openai` 0.1.14 or later, `@traceai/anthropic` 0.1.3 or later, `@traceai/bedrock` 0.1.1 or later, or `@traceai/langchain` 0.1.3 or later, as appropriate for your integration. When a call fails, traceAI marks the span `ERROR` and records the exception. Error text can carry the same data you hid with the other `hide_*` fields: a provider error body can quote your prompt back or include provider and gateway request IDs, and a framework error can include a stack trace with local file paths. `hide_error_details` keeps the fact that a span failed and what kind of failure it was, and drops the text. @@ -108,16 +110,16 @@ When a call fails, traceAI marks the span `ERROR` and records the exception. Err |-------|----------------|--------------------------|-------------------------| | Status code | Span status | `ERROR` | `ERROR` | | Status description | Span status | The exception message, never a traceback | Empty | -| `error.type` | Span attribute | The provider's error code when the SDK exposes one, otherwise the fully qualified exception class (e.g. `billing.errors.PaymentDeclined`), otherwise `_OTHER` | Kept | -| `exception.type` | `exception` event | The exception class | Kept | +| `error.type` | Span attribute | An instrumentor-supplied type or a provider error code; otherwise the exception class (module-qualified in Python, class name in TypeScript), or `_OTHER` if unknown | Kept | +| `exception.type` | `exception` event | The exception class in Python; a code or error name in TypeScript | Kept | | `exception.escaped` | `exception` event | Kept when set | Kept when set | -| `exception.message` | `exception` event | Kept | Dropped | -| `exception.stacktrace` | `exception` event | Kept | Dropped | -| `error.message` | Span attribute | Kept | Dropped | -| Other error-text attributes: any key ending in `.exception.message`, `.exception.stacktrace`, `.error.message` or `.error_message` (for example `autogen.error.message`) | Span attributes | Kept | Dropped | -| Output of a failed LangChain run (Python) | Span attributes | Kept. langchain-core fills it with the provider's error response | Dropped | +| `exception.message` | Span or event attribute | Kept | Dropped | +| `exception.stacktrace` | Span or event attribute | Kept | Dropped | +| `error.message` | Span or event attribute | Kept | Dropped | +| Other error-text attributes: any key ending in `.exception.message`, `.exception.stacktrace`, `.error.message` or `.error_message` (for example `autogen.error.message`) | Span or event attributes | Kept | Dropped | +| Output of a failed LangChain run (Python) | Span attributes | Kept unless output masking is enabled; it can contain the provider's error response | Dropped | -The status description never carries a traceback, whatever the setting. LangChain spans used to put the full traceback there; the stack trace now lives only in `exception.stacktrace` on the exception event. +The status description excludes tracebacks in either mode. When error details are enabled, stack traces belong in `exception.stacktrace` on the exception event. ### Default @@ -132,33 +134,24 @@ You rarely need to set `hide_error_details` yourself. When you don't set it in c The content fields count whether you set them in code or through their own environment variables, so `FI_HIDE_INPUTS=true` on its own also hides error details. `hide_input_images`, `hide_embedding_vectors`, `hide_llm_invocation_parameters`, and `pii_redaction` don't affect it. As with the other fields, a value set in code takes precedence over the environment variable. -This is a behaviour change if you already hide content. After you upgrade, setting any of the content fields above also hides error details: failed spans keep their `ERROR` status, `error.type`, and `exception.type`, but lose the status description, exception message, and stack trace. Set `hide_error_details=False` (or `FI_HIDE_ERROR_DETAILS=false`) to keep them. +If you already hide content, upgrading also hides error details by default. To retain error text for debugging, set `hide_error_details=False` in Python, `hideErrorDetails: false` in TypeScript, or `FI_HIDE_ERROR_DETAILS=false`. Error messages can expose prompts and other sensitive data even when inputs and outputs are hidden; only enable them when that data is safe to export. -`hide_error_details` applies to spans created through the shared traceAI wrapper (`FiSpan` / `FITracer`): spans from the instrumentors that use it, spans you start through `FITracer`, and an exception recorded automatically when it escapes a span's context manager. A span you start with a plain OpenTelemetry tracer isn't filtered. +### Scope - -These instrumentors bypass the shared wrapper, so neither the content `hide_*` fields nor `hide_error_details` apply to their spans yet. Fixes for them are being followed up. +`hide_error_details` applies to spans created through `FITracer` and instrumentors that use the shared traceAI span wrapper. In Python, this includes exceptions recorded automatically when they escape a wrapped span's context manager. Released instrumentors such as `traceai-chromadb` 0.2.0 use this wrapper; they do not need a separate privacy adapter. -- Python: a2a, beeai, strands, claude-agent-sdk, pydantic-ai, agno, pipecat, mcp, and the vector stores chromadb, lancedb, milvus, mongodb-vector, pgvector, pinecone, qdrant, redis-vector and weaviate (17 packages), plus livekit. -- TypeScript: `@traceai/llamaindex`, `@traceai/vercel` and `@traceai/mastra`. + +This setting is not an exporter-wide filter. A span created with a plain OpenTelemetry tracer is not filtered just because it uses a Future AGI exporter. Native integrations have their own content controls unless their guide explicitly documents support for `TraceConfig`. Follow the integration's privacy instructions or apply redaction in an OpenTelemetry Collector before export. Avoid sensitive values in custom attribute keys, span names, and event names; `hide_error_details` filters the error fields listed above, not arbitrary text. -### Content-hiding fixes in the same release - -These are privacy fixes for anyone who already uses `FI_HIDE_*`: - -- `hide_inputs` / `hideInputs` now also redacts `raw.input` and the prompt-template variables (`llm.prompt_template.variables` / `gen_ai.prompt.template.variables`). `hide_outputs` / `hideOutputs` now also redacts `raw.output`. -- TypeScript now masks the attributes passed when a span is created (`startSpan` and `startActiveSpan`), and link attributes. Before, `FI_HIDE_INPUTS` did not mask prompts that instrumentors set at creation, which affected about 22 TypeScript instrumentors, `@traceai/openai` included. Every published `@traceai/fi-core` release up to 1.0.0 has this gap. - -### Behaviour changes (TypeScript) +Content masking also covers `raw.input`, prompt-template variables (`llm.prompt_template.variables` / `gen_ai.prompt.template.variables`), and `raw.output`. In TypeScript, attributes supplied at span creation and link attributes are masked too. Environment variables apply even when you omit `traceConfig`. -- `FI_HIDE_*` environment variables now apply even when no `traceConfig` is passed. -- Inside `FITracer.startActiveSpan`, the active span is now the `FISpan`, not the SDK span. Code that casts it to the SDK `Span` breaks there. +Inside TypeScript `FITracer.startActiveSpan`, use the OpenTelemetry span interface. The active span is an `FISpan` wrapper, not the SDK's concrete `Span` class. ### Example -Hide inputs and outputs but keep error messages and stack traces for debugging: +Hide inputs, outputs, and error details. Configure your [Future AGI credentials](/docs/sdk/tracing/environment-variables) before registering the provider: @@ -175,8 +168,8 @@ Hide inputs and outputs but keep error messages and stack traces for debugging: config = TraceConfig( hide_inputs=True, hide_outputs=True, - # Without this line, hide_inputs would also hide error details - hide_error_details=False, + # Explicitly hide errors, even if the content flags change later + hide_error_details=True, ) OpenAIInstrumentor().instrument( @@ -203,8 +196,8 @@ Hide inputs and outputs but keep error messages and stack traces for debugging: traceConfig: { hideInputs: true, hideOutputs: true, - // Without this line, hideInputs would also hide error details - hideErrorDetails: false, + // Explicitly hide errors, even if the content flags change later + hideErrorDetails: true, }, }), ], @@ -215,8 +208,8 @@ Hide inputs and outputs but keep error messages and stack traces for debugging: ```bash export FI_HIDE_INPUTS=true export FI_HIDE_OUTPUTS=true - # Without this line, FI_HIDE_INPUTS would also hide error details - export FI_HIDE_ERROR_DETAILS=false + # Explicitly hide errors, even if the content flags change later + export FI_HIDE_ERROR_DETAILS=true ```