From dd15c67b4e3bf3091bcb0d61db0f2407a28316e2 Mon Sep 17 00:00:00 2001 From: Mounir Charef Date: Mon, 16 Nov 2026 17:07:11 +0100 Subject: [PATCH 1/5] docs: session details and trace export --- docs.json | 6 +- v3/data-governance/session-details.mdx | 52 ++++++++++++++++ v3/organization/trace-export.mdx | 86 ++++++++++++++++++++++++++ 3 files changed, 142 insertions(+), 2 deletions(-) create mode 100644 v3/data-governance/session-details.mdx create mode 100644 v3/organization/trace-export.mdx diff --git a/docs.json b/docs.json index e73a1a1b..9f2da0db 100644 --- a/docs.json +++ b/docs.json @@ -347,7 +347,8 @@ "pages": [ "v3/organization/users-organisation", "v3/organization/guardrails", - "v3/organization/management-api" + "v3/organization/management-api", + "v3/organization/trace-export" ] }, { @@ -360,7 +361,8 @@ "v3/data-governance/servers-location", "v3/data-governance/eu-endpoint", "v3/data-governance/static-ip", - "v3/data-governance/data-retention" + "v3/data-governance/data-retention", + "v3/data-governance/session-details" ] }, { diff --git a/v3/data-governance/session-details.mdx b/v3/data-governance/session-details.mdx new file mode 100644 index 00000000..6a11e3c8 --- /dev/null +++ b/v3/data-governance/session-details.mdx @@ -0,0 +1,52 @@ +--- +sidebarTitle: "Session Details" +title: "Session Data Recorded for LLM Calls" +icon: "list-tree" +description: "See what Eden AI records about each LLM call to group it into a session: ids and step counts, never prompt or answer text, and how an admin turns it off." +--- + +import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx"; + + + +To show the calls of one conversation together in Monitoring, Eden AI records a few facts about each LLM call next to its request log entry. None of them is prompt or answer text. + +## What is recorded + +| Fact | Where it comes from | +| --- | --- | +| Session id | The `session_id` body field, the `x-session-id` header, or the session a coding agent sends on its own (a header such as `x-claude-code-session-id`, Codex's `session-id` or `x-session-affinity`, or Claude Code's `metadata.user_id`) | +| Grouped session id | When a call names no session: the id of the session Eden AI groups it into, starting with `~`, stored with the request | +| End user id | `safety_identifier`, `user`, or Anthropic's `metadata.user_id`, as you send it | +| Agent ids | The subagent, turn and compaction markers a coding agent sends (Claude Code, Codex) | +| Trace ids | A W3C `traceparent` header you send | +| Step | How many messages the call carried, and whether it answered a user or tool results | +| Link hashes | Keyed hashes of the conversation's opening and of the last answer, so a call can be tied to the one it continues. They hold no text, and they are keyed with a secret only Eden AI holds, so they cannot be read back without it. | +| Tool names | The names of the tools a call used, **only when the request is saved** ([Log Retention](/v3/data-governance/data-retention)). Otherwise only how many there were. | + +## What is not recorded + +- Prompt or answer text, or tool arguments, unless you turned on Log Retention. +- Anything for calls that are not LLM calls, beyond the ids you send. + +Under [zero data retention](/v3/data-governance/compliance-policies), requests are never saved, so tool names are never recorded: only their number, the ids and the hashes. + +## Turn it off + +An organization admin can turn it off in **Settings > Request Settings > Session details**. From then on these facts are not recorded for any call of the organization, and Monitoring lists no new sessions. The setting does not change routing, billing or [trace export](/v3/organization/trace-export), which sends the sessions you name but never one Eden AI grouped on its own. + +## How long it is kept + +These facts are stored with your request log entries and kept for as long as they are. + +To group calls that name no session, Eden AI also keeps the link hashes of recent calls in its cache for 24 hours, then deletes them. A call that continues a conversation after that starts a new session. diff --git a/v3/organization/trace-export.mdx b/v3/organization/trace-export.mdx new file mode 100644 index 00000000..87ff4b9b --- /dev/null +++ b/v3/organization/trace-export.mdx @@ -0,0 +1,86 @@ +--- +sidebarTitle: "Trace Export" +title: "Send LLM Traces to Datadog and Langfuse" +icon: "chart-network" +description: "Export every LLM call to Datadog, Langfuse or any OpenTelemetry collector as an OTLP span with model, tokens, cost, key and session, nested in your traces." +--- + +import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx"; + + + +Eden AI can send each LLM call your organization makes to the tracing tool your team already uses, as an [OpenTelemetry](https://opentelemetry.io/) span. Calls that carry your own trace context join your traces, so the model call shows up under the request that made it. + +## Add a destination + +An organization admin adds destinations in **Settings > Trace Export**: + +| Tool | Endpoint | Credentials | +| --- | --- | --- | +| Datadog | `https://otlp.datadoghq.com/v1/traces` (use your Datadog site's host). Calls appear in LLM Observability, under the destination's service name as the ML app. | API key | +| Langfuse | `https://cloud.langfuse.com/api/public/otel/v1/traces` (`us.cloud.langfuse.com` in the US, or your own host) | Public and secret key | +| Any OTLP collector | Its OTLP/HTTP traces URL, ending in `/v1/traces` | Any headers it needs | + +Spans are sent as gzip-compressed OTLP/HTTP protobuf by a background worker, after your call has been answered: export never slows a call down. Credentials are stored encrypted and never shown again. When you edit a destination, leave them blank to keep them; if you change its tool or move its endpoint to another origin (another scheme, host or port), enter them again, since saved credentials are only ever sent where they were entered for. For an OTLP collector, **Remove the saved headers** sends the next calls with none. The page shows how many calls each destination received and its last error. + +### Choose which keys are sent + +By default a destination receives the calls of every API key of the organization. Two lists narrow it: + +- **Only these keys**: send only the calls of these keys. Leave it empty for every key. +- **Never these keys**: never send the calls of these keys. A key in both lists is never sent: exclusion wins. + +## Join your own traces + +Send a W3C `traceparent` header with the call. Its span then hangs under your span, in your trace: + +```python +import os +from openai import OpenAI + +client = OpenAI(base_url="https://api.edenai.run/v3", api_key=os.environ["EDENAI_API_KEY"]) + +response = client.chat.completions.create( + model="openai/gpt-4o-mini", + messages=[{"role": "user", "content": "Say hi"}], + extra_headers={ + "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01", + "x-session-id": "ticket-48213", + }, +) +print(response.choices[0].message.content) +``` + +In practice your OpenTelemetry SDK writes this header for you. Without one, each call is a trace of its own. A destination can also be set to ignore your trace and always send calls on their own. + +## What a span carries + +Each call is one span named `chat `, with one child span per provider attempt, named `chat ` after the model that attempt reached (a fallback makes two). Attributes follow the [OpenTelemetry GenAI conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/): + +| Attribute | Value | +| --- | --- | +| `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.provider.name` | The model you asked for, the one that answered, and its provider | +| `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.usage.cache_read.input_tokens` | Token counts, on the call's span only | +| `gen_ai.usage.cost` | What the call cost, in USD, on the call's span only. Not part of the conventions; Langfuse and most tools read it. A Datadog destination gets `gen_ai.usage.cost.amount` with `gen_ai.usage.cost.currency` instead, the names Datadog reads. | +| `gen_ai.conversation.id`, `session.id` | The session you named: the `session_id` body field, the `x-session-id` header, or the session a coding agent sends on its own (a header such as `x-claude-code-session-id`, Codex's `session-id` or `x-session-affinity`, or Claude Code's `metadata.user_id`). A session Eden AI grouped on its own, for calls that name none, is never exported. | +| `user.id` | The end user you named: `safety_identifier`, `user`, or Anthropic's `metadata.user_id` | +| `error.type` | Why a failed call or attempt failed | +| `edenai.api_key.name`, `edenai.routing.policy`, `edenai.tag.*` | The API key's name, the routing policy, and your request tags | + +Prompts and answers are left out unless you turn on **Include prompts and answers** for the destination, and never sent for a call under [zero data retention](/v3/data-governance/compliance-policies). When included, they follow the conventions' message format, in `gen_ai.system_instructions`, `gen_ai.input.messages` and `gen_ai.output.messages`; destinations other than Datadog also get them as `input.value` and `output.value`, which Langfuse and Phoenix read. Long texts and long histories are shortened, keeping the conversation's opening and its latest messages. + +## Sampling and limits + +- **Calls sent**: a share of calls per destination. When the call names a session, the share is picked by session, so a session is sent whole or not at all; otherwise by call. Failed calls are always sent. When you send a `traceparent` and the destination nests calls under your trace, its sampled flag decides instead, for failed calls too. +- **Retries**: when a destination is unreachable, times out, or answers 429, 502, 503 or 504, Eden AI retries with backoff, waiting as long as its `Retry-After` header asks, up to 5 minutes. After 10 failures in a row (about 13.5 minutes), the calls waiting for it are dropped. Any other error answer drops the batch at once, since sending it again would fail the same way. +- **Queue**: each destination holds up to 1,000 calls or 8 MB waiting to be sent. Calls past that, and calls waiting longer than 24 hours, are dropped. Every dropped call is counted on the destination. From 003bd6d38583be6853d9e6469818ac0b4f087681 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:07:29 +0000 Subject: [PATCH 2/5] chore: bump dateModified for changed docs --- v3/data-governance/session-details.mdx | 2 +- v3/organization/trace-export.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/v3/data-governance/session-details.mdx b/v3/data-governance/session-details.mdx index 6a11e3c8..881cf7d6 100644 --- a/v3/data-governance/session-details.mdx +++ b/v3/data-governance/session-details.mdx @@ -15,7 +15,7 @@ import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx"; about={"Data Compliance"} proficiencyLevel="Intermediate" keywords={["Eden AI", "sessions", "LLM tracing", "metadata", "GDPR", "zero data retention"]} - datePublished="2026-11-13T00:00:00Z" + datePublished="2026-11-16T00:00:00Z" dateModified="2026-11-16T00:00:00Z" /> diff --git a/v3/organization/trace-export.mdx b/v3/organization/trace-export.mdx index 87ff4b9b..28d88471 100644 --- a/v3/organization/trace-export.mdx +++ b/v3/organization/trace-export.mdx @@ -15,7 +15,7 @@ import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx"; about={"Observability"} proficiencyLevel="Intermediate" keywords={["Eden AI", "OpenTelemetry", "OTLP", "Datadog", "Langfuse", "LLM observability", "tracing"]} - datePublished="2026-11-13T00:00:00Z" + datePublished="2026-11-16T00:00:00Z" dateModified="2026-11-16T00:00:00Z" /> From da6b69915429794aef27553d47daeee2b7c615dc Mon Sep 17 00:00:00 2001 From: Mounir Charef Date: Mon, 16 Nov 2026 18:33:28 +0100 Subject: [PATCH 3/5] docs(trace-export): list the tools the setup presets --- v3/organization/trace-export.mdx | 38 ++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/v3/organization/trace-export.mdx b/v3/organization/trace-export.mdx index 28d88471..95a1e98a 100644 --- a/v3/organization/trace-export.mdx +++ b/v3/organization/trace-export.mdx @@ -1,20 +1,20 @@ --- sidebarTitle: "Trace Export" -title: "Send LLM Traces to Datadog and Langfuse" +title: "Send LLM Traces to Langfuse, Datadog and More" icon: "chart-network" -description: "Export every LLM call to Datadog, Langfuse or any OpenTelemetry collector as an OTLP span with model, tokens, cost, key and session, nested in your traces." +description: "Export every LLM call to Langfuse, LangSmith, Datadog, Grafana Cloud or any OpenTelemetry collector as an OTLP span with model, tokens, cost, key and session." --- import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx"; @@ -23,15 +23,29 @@ Eden AI can send each LLM call your organization makes to the tracing tool your ## Add a destination -An organization admin adds destinations in **Settings > Trace Export**: +An organization admin connects a tool in **Settings > Trace Export**: pick it, choose its region, and paste its keys. The setup fills in the tool's endpoint; for a self-hosted install, or a tool whose address is your account's own, enter it. -| Tool | Endpoint | Credentials | +| Tool | Regions | Credentials | | --- | --- | --- | -| Datadog | `https://otlp.datadoghq.com/v1/traces` (use your Datadog site's host). Calls appear in LLM Observability, under the destination's service name as the ML app. | API key | -| Langfuse | `https://cloud.langfuse.com/api/public/otel/v1/traces` (`us.cloud.langfuse.com` in the US, or your own host) | Public and secret key | -| Any OTLP collector | Its OTLP/HTTP traces URL, ending in `/v1/traces` | Any headers it needs | - -Spans are sent as gzip-compressed OTLP/HTTP protobuf by a background worker, after your call has been answered: export never slows a call down. Credentials are stored encrypted and never shown again. When you edit a destination, leave them blank to keep them; if you change its tool or move its endpoint to another origin (another scheme, host or port), enter them again, since saved credentials are only ever sent where they were entered for. For an OTLP collector, **Remove the saved headers** sends the next calls with none. The page shows how many calls each destination received and its last error. +| Langfuse | EU, US, Japan, HIPAA, or your own host | Public and secret key | +| LangSmith | US, EU, APAC, AWS, or your own host | API key, and optionally the project | +| Braintrust | US, EU | API key and project | +| Phoenix | Your Phoenix Cloud space's URL, or your own host | API key, when authentication is on | +| Opik | Comet Cloud, or your own host | API key, workspace, and optionally the project | +| Laminar | Cloud | Project API key | +| PostHog | US, EU | Project token | +| Logfire | US, EU | Write token | +| Datadog | US1, US3, US5, EU1, UK1, AP1, AP2. Calls appear in LLM Observability, with the destination's service name as the ML app. | API key | +| Grafana Cloud | Your stack's OTLP endpoint, followed by `/v1/traces` | Instance ID and token | +| New Relic | US, EU, Japan | License key | +| Honeycomb | US, EU. The service name is the dataset. | API key | +| Sentry | Your project's OTLP traces endpoint | Public key | +| Dynatrace | Your environment's OTLP traces URL | Token with `openpipeline:traces:ingest` | +| Elastic | Your managed OTLP endpoint, followed by `/v1/traces` | API key | +| SigNoz | US, EU, IN | Ingestion key | +| Any OTLP collector | Its OTLP/HTTP traces URL, most often ending in `/v1/traces` | Any headers it needs | + +Spans are sent as gzip-compressed OTLP/HTTP protobuf by a background worker, after your call has been answered: export never slows a call down. Credentials are stored encrypted and never shown again. When you edit a destination, leave them blank to keep them; if you move its endpoint to another origin (another scheme, host or port), enter them again, since saved credentials are only ever sent where they were entered for. To send to another tool, connect that tool as a new destination. For an OTLP collector, **Remove the saved headers** sends the next calls with none. The page shows how many calls each destination received and its last error. ### Choose which keys are sent From ff0c2b43260c8fdba85dfa92ca2d33d376c6c3f4 Mon Sep 17 00:00:00 2001 From: Mounir Charef Date: Tue, 17 Nov 2026 11:59:53 +0100 Subject: [PATCH 4/5] docs(trace-export): several destinations per tool, sampling and retry wording --- v3/organization/trace-export.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/v3/organization/trace-export.mdx b/v3/organization/trace-export.mdx index 95a1e98a..47943de1 100644 --- a/v3/organization/trace-export.mdx +++ b/v3/organization/trace-export.mdx @@ -23,7 +23,7 @@ Eden AI can send each LLM call your organization makes to the tracing tool your ## Add a destination -An organization admin connects a tool in **Settings > Trace Export**: pick it, choose its region, and paste its keys. The setup fills in the tool's endpoint; for a self-hosted install, or a tool whose address is your account's own, enter it. +An organization admin connects a tool in **Settings > Trace Export**: pick it, choose its region, and paste its keys. The setup fills in the tool's endpoint; for a self-hosted install, or a tool whose address is your account's own, enter it. A tool can have several destinations, one per project, environment or collector, each with its own keys and settings. | Tool | Regions | Credentials | | --- | --- | --- | @@ -45,7 +45,7 @@ An organization admin connects a tool in **Settings > Trace Export**: pick it, c | SigNoz | US, EU, IN | Ingestion key | | Any OTLP collector | Its OTLP/HTTP traces URL, most often ending in `/v1/traces` | Any headers it needs | -Spans are sent as gzip-compressed OTLP/HTTP protobuf by a background worker, after your call has been answered: export never slows a call down. Credentials are stored encrypted and never shown again. When you edit a destination, leave them blank to keep them; if you move its endpoint to another origin (another scheme, host or port), enter them again, since saved credentials are only ever sent where they were entered for. To send to another tool, connect that tool as a new destination. For an OTLP collector, **Remove the saved headers** sends the next calls with none. The page shows how many calls each destination received and its last error. +Spans are sent as gzip-compressed OTLP/HTTP protobuf by a background worker, after your call has been answered: export never slows a call down. Credentials are stored encrypted and never shown again. When you edit a destination, leave them blank to keep them; if you move its endpoint to another origin (another scheme, host or port), enter them again, since saved credentials are only ever sent where they were entered for. To send to another tool, connect that tool as a new destination. For an OTLP collector, or a tool whose key is optional (Phoenix), **Remove Saved Headers** sends the next calls with none. The page shows how many calls each destination received and its last error. ### Choose which keys are sent @@ -95,6 +95,6 @@ Prompts and answers are left out unless you turn on **Include prompts and answer ## Sampling and limits -- **Calls sent**: a share of calls per destination. When the call names a session, the share is picked by session, so a session is sent whole or not at all; otherwise by call. Failed calls are always sent. When you send a `traceparent` and the destination nests calls under your trace, its sampled flag decides instead, for failed calls too. -- **Retries**: when a destination is unreachable, times out, or answers 429, 502, 503 or 504, Eden AI retries with backoff, waiting as long as its `Retry-After` header asks, up to 5 minutes. After 10 failures in a row (about 13.5 minutes), the calls waiting for it are dropped. Any other error answer drops the batch at once, since sending it again would fail the same way. +- **Calls sent**: a share of calls per destination. When the call names a session, the share is picked by session; otherwise by call. Failed calls are always sent, unless they join a caller's trace that was not sampled: when you send a `traceparent` and the destination nests calls under your trace, its sampled flag decides first, for failed calls too. +- **Retries**: when a destination is unreachable, times out, or answers 429, 502, 503 or 504, Eden AI retries with backoff, doubling from 2 seconds up to 5 minutes, give or take a fifth, or waiting as long as its `Retry-After` header asks, up to 5 minutes per wait. After 10 failures in a row (about 13.5 minutes when the waits double, longer when `Retry-After` asks for more), the calls waiting for it are dropped. Any other error answer drops the batch at once, since sending it again would fail the same way. - **Queue**: each destination holds up to 1,000 calls or 8 MB waiting to be sent. Calls past that, and calls waiting longer than 24 hours, are dropped. Every dropped call is counted on the destination. From 20911d980d433086f83717d201c2cfc641e53e17 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 11:00:09 +0000 Subject: [PATCH 5/5] chore: bump dateModified for changed docs --- v3/data-governance/session-details.mdx | 4 ++-- v3/organization/trace-export.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/v3/data-governance/session-details.mdx b/v3/data-governance/session-details.mdx index 881cf7d6..1de0ae0d 100644 --- a/v3/data-governance/session-details.mdx +++ b/v3/data-governance/session-details.mdx @@ -15,8 +15,8 @@ import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx"; about={"Data Compliance"} proficiencyLevel="Intermediate" keywords={["Eden AI", "sessions", "LLM tracing", "metadata", "GDPR", "zero data retention"]} - datePublished="2026-11-16T00:00:00Z" - dateModified="2026-11-16T00:00:00Z" + datePublished="2026-11-17T00:00:00Z" + dateModified="2026-11-17T00:00:00Z" /> To show the calls of one conversation together in Monitoring, Eden AI records a few facts about each LLM call next to its request log entry. None of them is prompt or answer text. diff --git a/v3/organization/trace-export.mdx b/v3/organization/trace-export.mdx index 47943de1..ec9e7691 100644 --- a/v3/organization/trace-export.mdx +++ b/v3/organization/trace-export.mdx @@ -15,8 +15,8 @@ import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx"; about={"Observability"} proficiencyLevel="Intermediate" keywords={["Eden AI", "OpenTelemetry", "OTLP", "Langfuse", "LangSmith", "Datadog", "Grafana", "LLM observability", "tracing"]} - datePublished="2026-11-16T00:00:00Z" - dateModified="2026-11-16T00:00:00Z" + datePublished="2026-11-17T00:00:00Z" + dateModified="2026-11-17T00:00:00Z" /> Eden AI can send each LLM call your organization makes to the tracing tool your team already uses, as an [OpenTelemetry](https://opentelemetry.io/) span. Calls that carry your own trace context join your traces, so the model call shows up under the request that made it.