/applicationinsights-web-ts

GenAI Agent Traces — OpenTelemetry Semantic Conventions (distilled)

Reference for the gen_ai.* attributes the App Insights JavaScript SDK emits as Dependency telemetry so browser-side AI agent calls correlate with backend OpenTelemetry spans.

Stability opt-in. Set OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental in any backend that emits or reads these attributes. Without it, instrumentations may emit older/different attribute names.

Operation names (gen_ai.operation.name)

Span name MUST follow {operation.name} {target} — e.g. chat gpt-4o-mini, invoke_agent ResearchAssistant, execute_tool getWeather.

Provider names (gen_ai.provider.name)

openai, azure.ai.openai, azure.ai.inference, anthropic, aws.bedrock, gcp.gemini, gcp.vertex_ai, cohere, mistral_ai, groq, deepseek, perplexity, x_ai, ibm.watsonx.ai. Use lower-case, dotted form. New providers: use a stable lower-case identifier; no spaces.

Common request / response attributes (all spans)

Agent attributes

create_agent and invoke_agent spans are required to set gen_ai.agent.name. gen_ai.agent.id is required when known.

Tool attributes (execute_tool)

Sensitive content (Opt-In only)

Capture rules:

1. Off by default. Gate behind a runtime/config flag.
2. Truncate large content (e.g. > 8 KB) and set gen_ai.truncated=true.
3. Redact PII where required by policy before emitting.
4. For very large or sensitive payloads, emit a reference (e.g. blob URL) instead of inline content.

Token usage

• Set gen_ai.usage.input_tokens and gen_ai.usage.output_tokens on every model span (chat, text_completion, generate_content, embeddings — embeddings have no output tokens).
• For agents, sum tokens from child model spans onto the parent invoke_agent only when you have the totals. Never double-count by also summing nested agent invocations the parent didn't directly own.

Streaming

• Span ends when the stream completes (last chunk received OR client closes).
• gen_ai.usage.* and gen_ai.response.finish_reasons are set at end-of-stream.
• Optional event gen_ai.choice may be emitted per choice with index + finish reason for live dashboards.

Errors

• Set span status to ERROR.
• Set error.type to a stable identifier (HTTP status, provider error code, or exception class). Avoid free-form messages.
• For tool errors, the execute_tool span carries the error; the parent invoke_agent span only fails if the agent run aborted.

Mapping to App Insights

When emitting from the browser via the App Insights JS SDK, use Dependency telemetry with type: "GenAI" and put all gen_ai.* keys in properties. App Insights flattens properties into customDimensions, where they're queryable in KQL with tostring(customDimensions["gen_ai.operation.name"]).

Useful KQL

// Top agents by p95 latency
dependencies
| where type == "GenAI" and tostring(customDimensions["gen_ai.operation.name"]) == "invoke_agent"
| summarize p95=percentile(duration,95), runs=count()
    by agent=tostring(customDimensions["gen_ai.agent.name"])
| order by p95 desc

// Token usage by model
dependencies
| where type == "GenAI" and tostring(customDimensions["gen_ai.operation.name"]) == "chat"
| extend tin=toint(customDimensions["gen_ai.usage.input_tokens"]),
         tout=toint(customDimensions["gen_ai.usage.output_tokens"]),
         model=tostring(customDimensions["gen_ai.response.model"])
| summarize sum_in=sum(tin), sum_out=sum(tout), calls=count() by model

// Failed tool calls
dependencies
| where type == "GenAI" and tostring(customDimensions["gen_ai.operation.name"]) == "execute_tool"
| where success == false
| project timestamp, tool=tostring(customDimensions["gen_ai.tool.name"]),
          err=tostring(customDimensions["error.type"]), operation_Id

See also

• OTel GenAI spec: https://opentelemetry.io/docs/specs/semconv/gen-ai/
• Azure AI inference semconv: https://opentelemetry.io/docs/specs/semconv/gen-ai/azure-ai-inference/
• App Insights data model (Dependency): https://learn.microsoft.com/azure/azure-monitor/app/data-model-complete