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
35 changes: 35 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

---

## [2026-10-18]

### TypeScript

> **Security fix (all published `@traceai/fi-core` releases, 0.1.0 to 1.0.0):** content hiding did not apply to the attributes an instrumentation passes when it creates a span, and most instrumentations put the prompt there. With `FI_HIDE_INPUTS=true`, `@traceai/openai` still exported the prompt in `input.value`, `gen_ai.input.messages` and `raw.input`. Fixed in `@traceai/fi-core` 1.1.0. Upgrade it, and upgrade `@traceai/openai`, `@traceai/anthropic`, `@traceai/bedrock` and `@traceai/langchain` to the releases below: their published versions depend on `@traceai/fi-core` `^0.1.x` and keep the bug.

#### @traceai/fi-core `v1.1.0`
- 🔒 Attributes passed to `FITracer.startSpan` / `startActiveSpan` go through the same masking as `setAttribute(s)` (hide flags, PII redaction, error-detail hiding). They were exported unmasked. Samplers still see them, masked.
- 🔒 `hideInputs` also redacts `raw.input` and `llm.prompt_template.variables`; `hideOutputs` also redacts `raw.output`.
- ✨ New `hideErrorDetails` trace config option (`FI_HIDE_ERROR_DETAILS`). Unset, it turns on with any content-hiding flag (`hideInputs`, `hideOutputs`, `hideInputMessages`, `hideOutputMessages`, `hideInputText`, `hideOutputText`); explicit `true` / `false` wins. When on, ERROR statuses have no description, and `exception.message`, `exception.stacktrace`, `error.message` and keys ending in `.exception.message` / `.exception.stacktrace` / `.error.message` / `.error_message` are dropped from spans and events. Other attributes, `exception.type` included, are kept.
- ✨ Error spans carry `error.type` (provider error code, else error class). `exception.type` is the same in both modes and never a numeric code.
- 🐛 Status descriptions are the error message only, never a stack trace. Multi-line messages are kept whole, and a relayed Python traceback keeps its final `Type: message` line.
- 🐛 `FI_HIDE_*`, `FI_PII_REDACTION` and `FI_BASE64_IMAGE_MAX_LENGTH` env vars apply even when no `traceConfig` is passed.
- ⚠️ Behaviour change: users of the hide flags now also get error details hidden, and creation-time content redacted.
- ⚠️ Behaviour change: inside `FITracer.startActiveSpan`, `trace.getActiveSpan()` is the `FISpan`, not the SDK span. Code that casts it to the SDK `Span` / `ReadableSpan` breaks there.

#### @traceai/openai `v0.1.14`
- 🔒 Depends on `@traceai/fi-core` 1.1.0, so the prompt passed at span creation is hidden by the hide flags.

#### @traceai/anthropic `v0.1.3`
- 🔒 Depends on `@traceai/fi-core` 1.1.0, so the prompt passed at span creation is hidden by the hide flags.

#### @traceai/bedrock `v0.1.1`
- 🐛 Non-`Error` failures (cross-realm errors, thrown strings, plain objects) get an exception event, `error.type` and a message-only description instead of `String(error)`.
- 🔒 Depends on `@traceai/fi-core` 1.1.0.

#### @traceai/langchain `v0.1.3`
- 🐛 Status description is the error message, not LangChain's `run.error` (message plus full stack trace).
- 🔒 Depends on `@traceai/fi-core` 1.1.0 (prompt template variables are hidden with `hideInputs`).

#### @traceai/openai-agents `v0.2.1`
- 🐛 Status description is the error message only; error `data` moves to the exception event, whose type is `AgentSpanError`.

---

## [2025-07-08]

### Python
Expand Down
19 changes: 19 additions & 0 deletions docs/configuration/trace-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,10 +76,29 @@ const instrumentation = new OpenAIInstrumentation({
hideOutputText: true,
hideEmbeddingVectors: true,
base64ImageMaxLength: 16000,
// Optional: defaults to on whenever any of the content-hiding flags above is on
hideErrorDetails: true,
}
});
```

In TypeScript (`@traceai/fi-core` 1.1.0+), the masking also covers the attributes an instrumentation passes when it creates a span (most instrumentations put the prompt there). Earlier versions exported those unmasked. Besides `input.value` / `output.value` and the input / output messages, `hideInputs` redacts `raw.input` (the raw request body) and `llm.prompt_template.variables`, and `hideOutputs` redacts `raw.output`.

### Error details (TypeScript)

Error text can quote hidden content: provider error bodies echo prompts, and stack traces carry local file paths. `@traceai/fi-core` 1.1.0+ handles errors like this:

- Always: the span keeps status `ERROR` and gets `error.type` (the provider error code such as `model_not_found` when there is one, otherwise the error class name). The status description is the error message only, never a stack trace. The stack trace stays in `exception.stacktrace` on the exception event.
- With `hideErrorDetails` on, the `ERROR` status has no description, and these keys are dropped from span attributes, exception events and other events:
- `exception.message`
- `exception.stacktrace`
- `error.message`
- instrumentor-specific keys ending in `.exception.message`, `.exception.stacktrace`, `.error.message` or `.error_message` (for example `autogen.error.message`, `autogen.tool.error_message`)

Every other attribute is kept, including `exception.type`, `exception.escaped` and `error.type`. This is the same key list as Python.

`hideErrorDetails` (env `FI_HIDE_ERROR_DETAILS`) is tri-state. When you don't set it, it is on if any of `hideInputs`, `hideOutputs`, `hideInputMessages`, `hideOutputMessages`, `hideInputText` or `hideOutputText` is on. Set it to `false` explicitly to keep error details while hiding content.

## Configuration Precedence

Configuration is applied in this order (later overrides earlier):
Expand Down
22 changes: 22 additions & 0 deletions docs/typescript/fi-core.md
Original file line number Diff line number Diff line change
Expand Up @@ -344,10 +344,32 @@ const instrumentation = new OpenAIInstrumentation({
hideOutputText: false,
hideEmbeddingVectors: true,
base64ImageMaxLength: 16000,
// Optional. Unset, it is on whenever any of hideInputs, hideOutputs,
// hideInputMessages, hideOutputMessages, hideInputText or hideOutputText is on.
hideErrorDetails: true,
}
});
```

### Error details

A failed span always keeps status `ERROR` and gets `error.type` (the provider error code such as
`model_not_found` or `not_found_error` when the error has one, otherwise the error class name).
Its status description is the error message only, never a stack trace; the stack trace stays in
`exception.stacktrace` on the exception event.

With `hideErrorDetails` on (env `FI_HIDE_ERROR_DETAILS`), the `ERROR` status has no description,
and `exception.message`, `exception.stacktrace`, `error.message` and instrumentor keys ending in
`.exception.message`, `.exception.stacktrace`, `.error.message` or `.error_message` are dropped from
span attributes, exception events and other events. Everything else is kept, including
`exception.type`, `exception.escaped` and `error.type`. Error text is content: provider error
bodies can quote the prompt back. Set `hideErrorDetails: false` to keep error details while hiding
content.

Masking applies to the attributes passed when a span is created (`FITracer.startSpan` /
`startActiveSpan` options) as well as to attributes set later. `hideInputs` also redacts
`raw.input` and `llm.prompt_template.variables`; `hideOutputs` also redacts `raw.output`.

## Error Handling

```typescript
Expand Down
27 changes: 27 additions & 0 deletions typescript/packages/fi-core/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,30 @@
## [1.1.0] - 2026-10-18
### Security fix: content hiding skipped the attributes passed when a span is created
- **This bug predates 1.1.0: it is in every published release, 0.1.0 to 1.0.0.** `FITracer.startSpan` handed `options.attributes` straight to the OpenTelemetry span, so attributes passed at span creation skipped `FISpan` and every masking rule: `hideInputs` and the other hide flags, PII redaction, and (new in this release) error-detail hiding. About 22 instrumentations put the prompt there, `@traceai/openai` included, so with `FI_HIDE_INPUTS=true` the prompt was still exported in `input.value`, `gen_ai.input.messages` and `raw.input`.
- `FITracer.startSpan` and `startActiveSpan` now run creation-time attributes through the same masking as `setAttribute(s)` (`maskAttributes`). The masked attributes are still passed at creation, so a sampler sees the same values that are exported. An `error.type` passed at creation is kept.
- Content hiding now also covers the raw bodies and template variables: `hideInputs` redacts `raw.input` and `llm.prompt_template.variables`, `hideOutputs` redacts `raw.output` (as `input.value` / `output.value`).
- To get the fix, an instrumentation package must resolve `@traceai/fi-core` 1.1.0. Packages published with `^1.0.0` get it on upgrade. `@traceai/openai`, `@traceai/anthropic`, `@traceai/bedrock` and `@traceai/langchain` were published with `^0.1.x` and need the new releases that depend on `^1.1.0`.

### Feature
- New `hideErrorDetails` trace config option (env `FI_HIDE_ERROR_DETAILS`). When on, an ERROR status keeps no description, and `exception.message`, `exception.stacktrace`, `error.message` and instrumentor keys ending in `.exception.message` / `.exception.stacktrace` / `.error.message` / `.error_message` are dropped from span attributes, exception events and other events. It is a denylist, as in the Python core: `exception.type`, `exception.escaped`, `error.type` and every other attribute are kept. `FISpan` enforces it for `recordException`, `setStatus`, `addEvent` and `setAttribute(s)`, and `FITracer` for creation-time attributes, so every instrumentation that goes through `FITracer` gets it.
- Tri-state: when neither the option nor the env var is set, `hideErrorDetails` is on whenever any of `hideInputs`, `hideOutputs`, `hideInputMessages`, `hideOutputMessages`, `hideInputText` or `hideOutputText` is on. An explicit `true` / `false` (option or env) wins.
- Spans that end in ERROR now carry `error.type`: the provider error code when the error has one (OpenAI-compatible `code` such as `model_not_found`, Anthropic's body `error.type` such as `not_found_error`, Node's `ECONNREFUSED`, OpenAI `type` when there is no code), otherwise the error class name, otherwise `_OTHER`. An `error.type` set by the instrumentation is kept.
- `exception.type` is the same in both modes: a string `code` that is an identifier (as the OpenTelemetry SDK records it), otherwise the error name / class. A numeric code such as an HTTP `400` is no longer recorded as the type (the SDK alone would record `"400"`); Python records the class too.
- Exports `generateTraceConfig`, `getErrorType`, `getExceptionType`, `getErrorMessage`, `stripStackTrace` and the error / exception attribute key constants.

### Fix
- An ERROR status description is the error message only: `FISpan.setStatus` strips JavaScript stack frames and relayed Python tracebacks, and reduces `"<Name>: <message>"` (`String(error)`) to the message of the recorded exception. A multi-line message is kept whole when the description is a full `err.stack`, and a relayed Python traceback keeps its final `Type: message` line.
- `FITracer.startActiveSpan` makes the `FISpan` the active span, so `trace.getActiveSpan()` inside the callback goes through masking and the error-detail policy instead of reaching the raw span.
- `FI_HIDE_*`, `FI_BASE64_IMAGE_MAX_LENGTH` and `FI_PII_REDACTION` env vars are now read when an instrumentation is created without a `traceConfig`. Before, they only applied when a `traceConfig` object was passed.

### Behaviour change
- Attributes passed at span creation are now masked (see the security fix). If you set a hide flag, values you saw before in `input.value`, `gen_ai.input.messages`, `raw.input`, `raw.output` or `llm.prompt_template.variables` are now redacted or dropped.
- If you set any of the content-hiding flags above (option or env), error messages, stack traces and status descriptions are now hidden as well. Set `hideErrorDetails: false` (or `FI_HIDE_ERROR_DETAILS=false`) to keep them.
- If you set `FI_HIDE_*` env vars without passing a `traceConfig`, they now take effect. So do `FI_PII_REDACTION` and `FI_BASE64_IMAGE_MAX_LENGTH`.
- Error spans get a new `error.type` attribute.
- Inside `FITracer.startActiveSpan`, `trace.getActiveSpan()` returns the `FISpan`, not the SDK span. Code that casts it to the SDK `Span` or `ReadableSpan` (e.g. to read `.attributes` or `.name`) no longer works there; use the span passed to the callback through the `Span` API instead.
- `FISpan.recordException` builds the exception event itself (same keys as the SDK) instead of calling the SDK's `recordException`.

## [0.1.10] - 2025-06-10
### Feature
- Updated OpenTelemetry to v2.0.1
Expand Down
2 changes: 1 addition & 1 deletion typescript/packages/fi-core/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@traceai/fi-core",
"version": "1.0.0",
"version": "1.1.0",
"description": "Core OpenTelemetry instrumentation for TypeScript",
"main": "./dist/src/index.js",
"module": "./dist/esm/index.js",
Expand Down
Loading
Loading