This feature is in early access and behind a feature flag. Contact your Augment Solutions Architect to enable it for your tenant
Attribute names follow OpenTelemetry conventions wherever one exists. Names starting with
cosmos. are Cosmos-specific, for things OpenTelemetry has no name for: on spans, only cosmos.trigger, cosmos.credits, cosmos.cost_usd and cosmos.system_prompt.hash; plus Cosmos’s own metrics and log event attributes.
Resource and scope
Every request groups its spans by session and agent runtime version. Each group has one resource.Spans
Span names and kinds
Tool and subagent names contain only letters, digits and
._:/-, at most 128 characters (64 for agent names); a name that doesn’t match is replaced with the bare operation, for example execute_tool. Expert and model picker names are display names: they’re flattened to one line, cut to 128 bytes, and not sent at all if they contain something that looks like a credential.
Setup steps
Setup spans cover the time before the agent can respond. Their names are fixed.{server} is the MCP server’s name. For a server the agent couldn’t load and never learned the name of, it’s the partner’s catalog name, such as atlassian, or config- and the first 8 characters of the server’s configuration ID.
Setup steps under a run carry the run’s gen_ai.agent.id and cosmos.trigger, so a failed step tells you which expert and trigger it affected. Steps before the first run, or between runs, carry the session’s gen_ai.agent.id and no trigger.
| prepare_runtime | Any other setup | prepare_failed |
Attributes on every span
Session, run and agent spans
The run span has an
agent_ready event at the time the agent received the message. The time from the run’s start to agent_ready is the setup time the user waited for.
A run started by another session, such as a delegated worker, has a link to the calling tool span, with the caller’s session ID in the link’s gen_ai.conversation.id attribute. A message that Cosmos refused because the organization or user hit a usage limit or ran out of credits produces a run span with error.type = usage_limit_reached or credits_depleted, linked to the run it would have started. These spans are a signal, not an audit log: Cosmos sends at most one per session and reason per minute, at most 60 per organization per minute from each Cosmos server, and none for other kinds of refusal.
Model request spans
Usage, credits and cost are on attempt spans only, so summing them over all
chat spans never counts a retried request twice. A request that failed before any response carries no usage.
cosmos.system_prompt.hash is computed from the system instructions before redaction and before content limits, so you can’t always recompute it from gen_ai.system_instructions. Compare hashes with each other rather than with your own hash of the exported text.
Tool call spans
MCP attributes
On MCP tool calls (mcp.method.name = tools/call) and MCP server connections (mcp.method.name = initialize).
Trace context to MCP servers. On each
tools/call request, Cosmos sends the W3C traceparent of the tool call’s span in params._meta, as the OpenTelemetry MCP conventions describe. If your MCP server is instrumented and sends to the same platform, its spans appear under the Cosmos tool call in the same trace.
Content attributes
Sent only for the content levels an admin turned on, within the destination’s content limit. Values are JSON strings.
A subagent’s tool call spans carry timing, status and
error.type, but no arguments or results, even with Tool inputs and outputs on.
Model inputs includes the results of earlier tool calls, because they’re part of what the model is sent. Turning Tool inputs and outputs off doesn’t remove that text from gen_ai.input.messages when Model inputs is on.
With Model inputs, consecutive model requests send only what changed. A model request span that continues an earlier one has a span link to it in the same trace. A model request without a link starts a new chain and carries its full input. This happens on purpose when the history no longer matches the previous request (for example after context compaction), after spans were lost on the way, or when the previous request’s content wasn’t fully captured.
To rebuild a request’s full input, follow the links back to a span without one, then walk forward:
gen_ai.input.messages: append each span’s messages to the ones before. An empty list means no new messages.gen_ai.system_instructionsandgen_ai.tool.definitions: a span sends them only when they changed. If a span doesn’t have one, keep the earlier value. An empty list means it was removed.
Status
Values and limits
-
Cosmos also accepts
gen_ai.request.max_tokens,gen_ai.request.temperature,gen_ai.request.top_p,gen_ai.request.stream,gen_ai.usage.reasoning.output_tokens,process.exit.code,jsonrpc.request.idandnetwork.protocol.version, but the current Cosmos agent doesn’t send them, so don’t build dashboards on them yet. Reasoning tokens are counted ingen_ai.usage.output_tokens. -
Free-text values, such as
gen_ai.agent.nameand status messages, have credentials, emails, paths and long identifiers redacted. Attributes are cut to 256 characters and status messages to 1 KB. Identifiers, model names and enumerated values must match a fixed format, or the attribute isn’t sent. - A span has at most 64 attributes.
- Attribute names and values are checked against an allowlist. Anything not listed on this page isn’t sent, including Cosmos-internal identifiers, environment and infrastructure details, and model reasoning text.
Error types
error.type is a short, low-cardinality value, safe to group and alert on.
Model request and tool spans carry the error type the agent classified:
MCP server failures
A failedinitialize {server} or mcp_server_unavailable {server} span has one of these 17 error.type values and its fixed status message. The server’s own error text is never sent.
mcp_name_collision isn’t counted in cosmos.mcp.connection.failures, because the server with that name may be working.
Metrics
Sent to/v1/metrics when Send metrics is on, every 60 seconds, with cumulative temporality. Histograms use explicit bucket boundaries. Metrics are derived from the same exported spans, so they follow the same Sessions to export and Include user identity settings.
user.id and user.email are present only with Include user identity on. Without it, the cosmos.* usage counters are totals by model. The usage counters carry both the requested and the served model, so a request for the default model is attributed to the model that served it, and a fallback to another model is visible.
A new counter series first reports 0, then its total, so rate and increase functions count its first event.
error.type values on otel.sdk.exporter.span.exported are queue_full, retry_exhausted, rejected, too_large, shutdown, destination_removed and policy_changed.
Histogram buckets
Aggregating metrics
- Totals are cumulative per Cosmos server instance, identified by
service.instance.id. Sum across instances, and use rate or increase functions rather than raw values. - Each metric holds at most 2,000 attribute combinations per destination, or 10,000 for combinations with a user. Further combinations go to one series with
otel.metric.overflow=true. - Totals restart, with a new start time, after two hours without spans, and when Sessions to export or Include user identity changes.
Log events
Sent to/v1/logs when Send logs is on. Each event is a log record with EventName and body set to the event name, the trace ID and span ID of the span it describes, and severity INFO, or ERROR when the span failed. Log events never contain content.
Subagent spans and retried requests’ parent spans have no events. A subagent’s tool calls do have
cosmos.tool.result events.
Event attributes
Test span
The connection test sends one span namedexport_test, status OK, with the resource attributes above and no other attributes. It has its own random trace ID.