# assistant-cloud/telemetry
URL: /docs/api-reference/integrations/assistant-cloud-telemetry

OpenTelemetry exporter, span processor and stream metadata helpers that send a server's GenAI spans to Assistant Cloud and hand the trace id to the browser.

> For AI agents: a documentation index is available at [llms.txt](/llms.txt). Use `.md` for canonical markdown pages; `.mdx` is kept as a backwards-compatible alias on supported URL paths.

`@opentelemetry/api`, `@opentelemetry/sdk-trace-base` and `@opentelemetry/exporter-trace-otlp-http` are optional peers needed only by this entry. The exporter posts OTLP/HTTP JSON to `POST /v1/traces` on `https://backend.assistant-api.com` with the project's API key, so it runs on the server only; the setup and the receiver's rules are on [Traces](/docs/cloud/traces).

## API Reference

### assistantCloudTraceExportOptions

- `options`: `AssistantCloudTraceExportOptions`

  - `apiKey`: `string`
  - `baseUrl?`: `string`
  - `headers?`: `Record<string, string>`

### assistantCloudTraceMetadata

```
function assistantCloudTraceMetadata(): { traceId?: string };
```

### createAssistantCloudSpanProcessor

- `exporter`: `SpanExporter`

  - `export`: `(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void) => void` — Called to export sampled ReadableSpans.
  - `shutdown`: `() => Promise<void>` — Stops the exporter.
  - `forceFlush?`: `() => Promise<void>` — Immediately export all spans

- `options?`: `AssistantCloudSpanProcessorOptions`
  - `filter?`: `(span: ReadableSpan) => boolean`

### createAssistantCloudTraceExporter

- `options`: `AssistantCloudTraceExportOptions`

  - `apiKey`: `string`
  - `baseUrl?`: `string`
  - `headers?`: `Record<string, string>`

### isAssistantCloudSpan

- `span`: `ReadableSpan`

  - `name`: `string`

  - `kind`: `SpanKind`

  - `spanContext`: `() => SpanContext`

  - `parentSpanContext?`: `SpanContext`

    - `traceId`: `string` — The ID of the trace that this span belongs to. It is worldwide unique with practically sufficient probability by being made as 16 randomly generated bytes, encoded as a 32 lowercase hex characters corresponding to 128 bits.

    - `spanId`: `string` — The ID of the Span. It is globally unique with practically sufficient probability by being made as 8 randomly generated bytes, encoded as a 16 lowercase hex characters corresponding to 64 bits.

    - `isRemote?`: `boolean` — Only true if the SpanContext was propagated from a remote parent.

    - `traceFlags`: `number` — Trace flags to propagate. It is represented as 1 byte (bitmap). Bit to represent whether trace is sampled or not. When set, the least significant bit documents that the caller may have recorded trace data. A caller who does not record trace data out-of-band leaves this flag unset. see TraceFlags for valid flag values.

    - `traceState?`: `TraceState` — Tracing-system-specific info to propagate. The tracestate field value is a \`list\` as defined below. The \`list\` is a series of \`list-members\` separated by commas \`,\`, and a list-member is a key/value pair separated by an equals sign \`=\`. Spaces and horizontal tabs surrounding \`list-members\` are ignored. There can be a maximum of 32 \`list-members\` in a \`list\`. More Info: https\://www\.w3.org/TR/trace-context/#tracestate-field Examples: Single tracing system (generic format): tracestate: rojo=00f067aa0ba902b7 Multiple tracing systems (with different formatting): tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

      - `set`: `(key: string, value: string) => TraceState` — Create a new TraceState which inherits from this TraceState and has the given key set. The new entry will always be added in the front of the list of states.
      - `unset`: `(key: string) => TraceState` — Return a new TraceState which inherits from this TraceState but does not contain the given key.
      - `get`: `(key: string) => string` — Returns the value to which the specified key is mapped, or \`undefined\` if this map contains no mapping for the key.
      - `serialize`: `() => string` — Serializes the TraceState to a \`list\` as defined below. The \`list\` is a series of \`list-members\` separated by commas \`,\`, and a list-member is a key/value pair separated by an equals sign \`=\`. Spaces and horizontal tabs surrounding \`list-members\` are ignored. There can be a maximum of 32 \`list-members\` in a \`list\`.

  - `startTime`: `HrTime`

  - `endTime`: `HrTime`

  - `status`: `SpanStatus`

    - `code`: `SpanStatusCode` — The status code of this message.
    - `message?`: `string` — A developer-facing error message.

  - `attributes`: `Attributes`

  - `links`: `Link[]`

  - `events`: `TimedEvent[]`

  - `duration`: `HrTime`

  - `ended`: `boolean`

  - `resource`: `Resource`

    - `asyncAttributesPending?`: `boolean` — Check if async attributes have resolved. This is useful to avoid awaiting waitForAsyncAttributes (which will introduce asynchronous behavior) when not necessary.
    - `attributes`: `Attributes`
    - `schemaUrl?`: `string`
    - `waitForAsyncAttributes?`: `() => Promise<void>` — Returns a promise that will never be rejected. Resolves when all async attributes have finished being added to this Resource's attributes. This is useful in exporters to block until resource detection has finished.
    - `merge`: `(other: Resource | null) => Resource` — Returns a new, merged Resource by merging the current Resource with the other Resource. In case of a collision, other Resource takes precedence.
    - `getRawAttributes`: `() => RawResourceAttribute[]`

  - `instrumentationScope`: `InstrumentationScope`

    - `name`: `string`
    - `version?`: `string`
    - `schemaUrl?`: `string`

  - `droppedAttributesCount`: `number`

  - `droppedEventsCount`: `number`

  - `droppedLinksCount`: `number`

### withAssistantCloudTraceMetadata

- `messageMetadata?`: `((options: { part: Part; }) => Record<string, unknown> | undefined)`