semconv

Documentation

Overview

Package semconv provides semantic conventions for Gen AI observability. These constants align with OpenTelemetry semantic conventions for generative AI.

Index

• Constants
• func SetBoolAttribute(span trace.Span, key string, value bool)
• func SetFloat64Attribute(span trace.Span, key string, value float64)
• func SetInt64Attribute(span trace.Span, key string, value int64)
• func SetIntAttribute(span trace.Span, key string, value int)
• func SetJSONAttribute(span trace.Span, key string, value interface{}) error
• func SetMessagesAttribute(span trace.Span, key string, messages []Message) error
• func SetStringAttribute(span trace.Span, key, value string)
• func SetStringSliceAttribute(span trace.Span, key string, values []string)
• func SetToolCallsAttribute(span trace.Span, key string, toolCalls []ToolCall) error
• func SetToolDefinitionsAttribute(span trace.Span, key string, tools []ToolDefinition) error
• type AttributeBuilder
  • func NewAttributeBuilder() *AttributeBuilder
  • func (ab *AttributeBuilder) Bool(key string, value bool) *AttributeBuilder
  • func (ab *AttributeBuilder) Build() []attribute.KeyValue
  • func (ab *AttributeBuilder) Float64(key string, value float64) *AttributeBuilder
  • func (ab *AttributeBuilder) Int(key string, value int) *AttributeBuilder
  • func (ab *AttributeBuilder) Int64(key string, value int64) *AttributeBuilder
  • func (ab *AttributeBuilder) SetAttributes(span trace.Span)
  • func (ab *AttributeBuilder) String(key, value string) *AttributeBuilder
  • func (ab *AttributeBuilder) StringSlice(key string, values []string) *AttributeBuilder
• type Message
• type MessagePart
• type ToolCall
• type ToolDefinition

Constants

const (
	CodingAgentVendorClaudeCode = "claude-code"
	CodingAgentVendorCursor     = "cursor"
	CodingAgentVendorCodex      = "codex"
	CodingAgentVendorWindsurf   = "windsurf"
)

Vendor identifiers (used as `gen_ai.agent.name` value).

const (
	// CodingAgentSessionID identifies a single coding-agent session.
	// Used as the join key across all spans/events emitted for that session.
	CodingAgentSessionID = "coding_agent.session.id"
	// CodingAgentClient is the vendor identifier; mirror of gen_ai.agent.name.
	// Carried separately so dashboard widgets can filter without
	// pulling in the full gen_ai.* attribute set.
	CodingAgentClient = "coding_agent.client"
	// CodingAgentClientVersion is the vendor's client version.
	CodingAgentClientVersion = "coding_agent.client.version"
	// CodingAgentSessionOutcome captures how the session ended.
	// One of: merged | committed | abandoned_no_change | abandoned_with_change | cancelled.
	CodingAgentSessionOutcome = "coding_agent.session.outcome"
	// CodingAgentSessionDurationMs is wall-clock duration in milliseconds.
	CodingAgentSessionDurationMs = "coding_agent.session.duration_ms"
	// CodingAgentSessionToolCallCount totals tool invocations during the session.
	CodingAgentSessionToolCallCount = "coding_agent.session.tool_call_count"
	// CodingAgentSessionSubagentCount totals child/subagent spawns.
	CodingAgentSessionSubagentCount = "coding_agent.session.subagent_count"
	// CodingAgentSessionCostUSD is the realized USD cost.
	CodingAgentSessionCostUSD = "coding_agent.session.cost_usd"

	// Per-session code-change rollups stamped on the
	// `coding_agent.session` root span at SessionEnd. They aggregate
	// edit / accept / reject / line counts the adapter observed
	// across the session so dashboards don't have to fan out into
	// every `coding_agent.edit.decision` span.
	//
	// Mirrors Claude Code's native `claude_code.lines_of_code.count`
	// metric shape — when the operator ships both paths (hook + native
	// OTel exporter), the query layer coalesces.
	CodingAgentSessionLinesAdded      = "coding_agent.session.lines.added"
	CodingAgentSessionLinesRemoved    = "coding_agent.session.lines.removed"
	CodingAgentSessionLinesAccepted   = "coding_agent.session.lines.accepted"
	CodingAgentSessionLinesRejected   = "coding_agent.session.lines.rejected"
	CodingAgentSessionEditAcceptCount = "coding_agent.session.edit.accept_count"
	CodingAgentSessionEditRejectCount = "coding_agent.session.edit.reject_count"
	CodingAgentSessionCommitCount     = "coding_agent.session.commit_count"
	CodingAgentSessionPRCount         = "coding_agent.session.pr_count"
)

Session structure attributes.

const (
	// CodingAgentSessionOutcomeCompleted — the agent reported a
	// successful end of the session (Cursor's reason="completed",
	// Claude Code's "stop", etc). The user may or may not have
	// merged anything; we stay agnostic on downstream VCS state.
	CodingAgentSessionOutcomeCompleted           = "completed"
	CodingAgentSessionOutcomeMerged              = "merged"
	CodingAgentSessionOutcomeCommitted           = "committed"
	CodingAgentSessionOutcomeAbandonedNoChange   = "abandoned_no_change"
	CodingAgentSessionOutcomeAbandonedWithChange = "abandoned_with_change"
	CodingAgentSessionOutcomeCancelled           = "cancelled"
)

Session outcome values.

const (
	// CodingAgentAgentID is a stable id for this agent instance within the
	// session (root or subagent). Use parent_id to walk the tree.
	CodingAgentAgentID = "coding_agent.agent.id"
	// CodingAgentAgentParentID points at the spawning agent's id.
	CodingAgentAgentParentID = "coding_agent.agent.parent_id"
	// CodingAgentAgentType is one of: main | subagent | task_tool.
	CodingAgentAgentType = "coding_agent.agent.type"
	// CodingAgentSubagentType is the vendor-specific subagent kind
	// (e.g. Claude Code's named subagents, Codex spawn types).
	CodingAgentSubagentType = "coding_agent.subagent.type"
	// CodingAgentLinkageConfidence reports how reliable the parent_id
	// linkage is for this vendor: high | medium | low.
	// Codex subagent linkage is often medium because parent is
	// inferred via process metadata rather than carried by the protocol.
	CodingAgentLinkageConfidence = "coding_agent.linkage_confidence"
)

Subagent linkage attributes.

const (
	CodingAgentAgentTypeMain     = "main"
	CodingAgentAgentTypeSubagent = "subagent"
	CodingAgentAgentTypeTaskTool = "task_tool"

	CodingAgentLinkageConfidenceHigh   = "high"
	CodingAgentLinkageConfidenceMedium = "medium"
	CodingAgentLinkageConfidenceLow    = "low"
)

const (
	// CodingAgentEditDecision is one of: accept | reject | modify | auto_accepted.
	CodingAgentEditDecision = "coding_agent.edit.decision"
	// CodingAgentEditDecisionSource is the trigger:
	// user_interactive | user_permanent_rule | hook | config | policy.
	CodingAgentEditDecisionSource = "coding_agent.edit.decision.source"
	// CodingAgentEditLinesAdded is the count of added lines.
	CodingAgentEditLinesAdded = "coding_agent.edit.lines.added"
	// CodingAgentEditLinesRemoved is the count of removed lines.
	CodingAgentEditLinesRemoved = "coding_agent.edit.lines.removed"
	// CodingAgentEditLanguage is the detected programming language.
	CodingAgentEditLanguage = "coding_agent.edit.language"
	// CodingAgentEditToolName is the tool that produced the edit
	// (e.g. "Edit", "Write", "Apply Patch").
	CodingAgentEditToolName = "coding_agent.edit.tool.name"
)

Edit decision attributes — captured per file/edit so dashboards can distinguish auto-applied agent edits from user-reviewed ones. OTel has no standard for this; this is the major gap we fill.

const (
	CodingAgentEditDecisionAccept       = "accept"
	CodingAgentEditDecisionReject       = "reject"
	CodingAgentEditDecisionModify       = "modify"
	CodingAgentEditDecisionAutoAccepted = "auto_accepted"

	CodingAgentEditDecisionSourceUserInteractive   = "user_interactive"
	CodingAgentEditDecisionSourceUserPermanentRule = "user_permanent_rule"
	CodingAgentEditDecisionSourceHook              = "hook"
	CodingAgentEditDecisionSourceConfig            = "config"
	CodingAgentEditDecisionSourcePolicy            = "policy"
)

const (
	// CodingAgentToolTriggeringLLMRequestID is the LLM response id
	// whose tool_calls produced this invocation.
	CodingAgentToolTriggeringLLMRequestID = "coding_agent.tool.triggering_llm_request_id"
	// CodingAgentToolIteration is the loop index for retried/iterated tools.
	CodingAgentToolIteration = "coding_agent.tool.iteration"
	// CodingAgentToolGroupID groups tools fired in the same model turn.
	CodingAgentToolGroupID = "coding_agent.tool.group.id"
	// CodingAgentToolGroupType describes the group's intent
	// (e.g. "file_edit", "search", "bash").
	CodingAgentToolGroupType = "coding_agent.tool.group.type"
)

Tool causality attributes — link tool invocations back to the model turn that triggered them. OTel typed span links (PR #3575) will replace these once they ship; until then, this is the explicit join key.

const (
	// CodingAgentMCPServerName is the MCP server identifier.
	CodingAgentMCPServerName = "coding_agent.mcp.server.name"
	// CodingAgentMCPScope is one of: user | project | local | enterprise.
	CodingAgentMCPScope = "coding_agent.mcp.scope"
	// CodingAgentMCPTransport is one of: stdio | sse | streamable_http.
	CodingAgentMCPTransport = "coding_agent.mcp.transport"
	// CodingAgentMCPSource is one of: builtin | plugin | marketplace.
	CodingAgentMCPSource = "coding_agent.mcp.source"
)

MCP server attribution.

const (
	CodingAgentMCPScopeUser       = "user"
	CodingAgentMCPScopeProject    = "project"
	CodingAgentMCPScopeLocal      = "local"
	CodingAgentMCPScopeEnterprise = "enterprise"

	CodingAgentMCPTransportStdio          = "stdio"
	CodingAgentMCPTransportSSE            = "sse"
	CodingAgentMCPTransportStreamableHTTP = "streamable_http"

	CodingAgentMCPSourceBuiltin     = "builtin"
	CodingAgentMCPSourcePlugin      = "plugin"
	CodingAgentMCPSourceMarketplace = "marketplace"
)

const (
	// CodingAgentUserClassification is one of: personal | work | disputed | unknown.
	// Stamped at hook-time using API-key allowlist + repo-origin allowlist.
	CodingAgentUserClassification = "coding_agent.user.classification"
	// CodingAgentUserClassificationReason explains the classification
	// (e.g. "api_key_allowlist", "repo_origin_match", "no_signal").
	CodingAgentUserClassificationReason = "coding_agent.user.classification.reason"
	// CodingAgentPolicyPermissionMode captures how permissive the run is
	// (e.g. "interactive", "auto_accept", "dangerously_skip_permissions").
	CodingAgentPolicyPermissionMode = "coding_agent.policy.permission_mode"
	// CodingAgentContentCaptureMode is the active capture posture:
	// minimal | metadata_only | full. See `cli/internal/otlp/attrs.go`
	// for the per-mode attribute matrix.
	CodingAgentContentCaptureMode = "coding_agent.content_capture_mode"
)

Identity & policy attributes.

const (
	CodingAgentUserClassificationPersonal = "personal"
	CodingAgentUserClassificationWork     = "work"
	CodingAgentUserClassificationDisputed = "disputed"
	CodingAgentUserClassificationUnknown  = "unknown"

	// CodingAgentContentCaptureMinimal — only session bookends and
	// rolled-up counters. No per-event spans. Cheapest tier; for
	// enterprises that want budget visibility without per-prompt
	// content. See Phase C of the coding-agents plan.
	CodingAgentContentCaptureMinimal = "minimal"
	// CodingAgentContentCaptureMetadataOnly — per-event spans with
	// counts/timings/cost/repo but redacted bodies (no prompts, no
	// tool args, no shell flags). Recommended default.
	CodingAgentContentCaptureMetadataOnly = "metadata_only"
	// CodingAgentContentCaptureFull — everything metadata mode has
	// plus prompts, responses, thoughts, tool args, tool results.
	// Tier-2 PII redaction still runs. For trust+safety reviews.
	CodingAgentContentCaptureFull = "full"
)

const (
	// CodingAgentLoopDetected is true when an in-session loop is detected.
	CodingAgentLoopDetected = "coding_agent.loop.detected"
	// CodingAgentLoopPattern names the pattern (e.g. "edit_revert_edit",
	// "tool_retry").
	CodingAgentLoopPattern = "coding_agent.loop.pattern"
)

Loop detection.

const (
	// CodingAgentHookEvent names the originating hook event (e.g. "PreToolUse").
	CodingAgentHookEvent = "coding_agent.hook.event"
	// CodingAgentHookCLIVersion identifies the shield360 CLI version.
	CodingAgentHookCLIVersion = "coding_agent.hook.cli.version"
	// CodingAgentHookSchemaVersion is the wire-format schema version.
	// Bump when a breaking change is necessary; receivers read this to
	// stay forward-compatible with the latest CLIs.
	CodingAgentHookSchemaVersion = "coding_agent.hook.schema.version"
)

Hook plumbing — these are reserved attributes the CLI stamps on every hook invocation so we can debug and version the wire format.

const (
	CodingAgentSpanSession      = "coding_agent.session"
	CodingAgentSpanToolCall     = "coding_agent.tool.call"
	CodingAgentSpanEditDecision = "coding_agent.edit.decision"
	CodingAgentSpanSubagent     = "coding_agent.subagent"
	CodingAgentSpanLLMTurn      = "coding_agent.llm.turn"
	// CodingAgentSpanGitCommit is emitted when the agent's Bash /
	// shell tool ran a `git commit` invocation. One span per detected
	// commit, child of the session-root trace.
	CodingAgentSpanGitCommit = "coding_agent.git.commit"
	// CodingAgentSpanGitPullRequest is emitted when the agent's
	// Bash / shell tool created a pull / merge request (`gh pr
	// create`, `git push -u origin <branch>` that produced a PR URL,
	// etc.).
	CodingAgentSpanGitPullRequest = "coding_agent.git.pull_request"
)

Span names emitted by the CLI normalizer. Keep these as constants so dashboard SQL can match against a small, stable set.

const (
	CodingAgentGitCommitSHA     = "coding_agent.git.commit.sha"
	CodingAgentGitCommitMessage = "coding_agent.git.commit.message"
	CodingAgentGitPRURL         = "coding_agent.git.pull_request.url"
	CodingAgentGitPRNumber      = "coding_agent.git.pull_request.number"
	CodingAgentGitPRTitle       = "coding_agent.git.pull_request.title"
)

Git commit / pull-request attributes — attached to the matching `coding_agent.git.commit` / `coding_agent.git.pull_request` span. The body-bearing values (commit message, PR title) are stamped only under `full` content capture; the SHA / URL / number are always safe to stamp.

const (
	CodingAgentEventSessionStart    = "coding_agent.session.start"
	CodingAgentEventSessionEnd      = "coding_agent.session.end"
	CodingAgentEventEditDecision    = "coding_agent.edit.decision"
	CodingAgentEventLoopDetected    = "coding_agent.loop.detected"
	CodingAgentEventSubagentSpawned = "coding_agent.subagent.spawned"
	CodingAgentEventSubagentDone    = "coding_agent.subagent.completed"
	CodingAgentEventMCPInvoked      = "coding_agent.mcp.tool.invoked"
)

Event names — emitted as span events for high-cardinality moments where a separate span would be overkill.

const (
	CodingAgentMetricSessionDuration  = "coding_agent.session.duration"
	CodingAgentMetricSessionCostUSD   = "coding_agent.session.cost_usd"
	CodingAgentMetricSessionToolCalls = "coding_agent.session.tool_call_count"
	CodingAgentMetricSessionSubagents = "coding_agent.session.subagent_count"
	CodingAgentMetricToolDuration     = "coding_agent.tool.duration"
	CodingAgentMetricEditDecisions    = "coding_agent.edit.decision.count"
	// CodingAgentMetricLinesOfCode is a counter of added / removed
	// lines tagged with `type=added|removed`, `decision`, `vendor`, `user`.
	CodingAgentMetricLinesOfCode = "coding_agent.lines_of_code.count"
	// CodingAgentMetricEditDecisionCnt is a counter of edit
	// decisions tagged with `decision`, `vendor`, `tool_name`,
	// `language`, `user`. Renamed under our namespace from
	// `claude_code.code_edit_tool.decision`.
	CodingAgentMetricEditDecisionCnt = "coding_agent.code_edit_tool.decision"
	// CodingAgentMetricCommit is a counter of agent-attributed
	// git commits tagged with `vendor`, `user`.
	CodingAgentMetricCommit = "coding_agent.commit.count"
	// CodingAgentMetricPullRequest is a counter of agent-attributed
	// pull / merge requests tagged with `vendor`, `user`.
	CodingAgentMetricPullRequest = "coding_agent.pull_request.count"
)

Metric names — additions on top of gen_ai.* metrics.

The `coding_agent.lines_of_code.count`, `coding_agent.code_edit_tool.decision`, `coding_agent.commit.count`, and `coding_agent.pull_request.count` counters mirror Claude Code's native exporter shape (`claude_code.lines_of_code.count` …) under our canonical namespace. They are emitted alongside the matching span so backends that consume metrics (Prometheus / Mimir) see the same numbers traces backends do.

const (
	// GenAIOperationName is the name of the operation being performed
	GenAIOperationName = "gen_ai.operation.name"

	// GenAIOperationTypeChat represents a chat completion operation
	GenAIOperationTypeChat = "chat"
	// GenAIOperationTypeCompletion represents a text completion operation
	GenAIOperationTypeCompletion = "completion"
	// GenAIOperationTypeEmbedding represents an embedding operation
	GenAIOperationTypeEmbedding = "embedding"
	// GenAIOperationTypeImage represents an image generation operation
	GenAIOperationTypeImage = "image"
	// GenAIOperationTypeAudio represents an audio generation operation
	GenAIOperationTypeAudio = "audio"
)

Operation Types

const (
	// GenAISystem is the legacy attribute name. Treat as deprecated;
	// emit GenAIProviderName alongside it for new code paths.
	GenAISystem = "gen_ai.system"
	// GenAIProviderName is the OTel 1.36+ canonical attribute name
	// for the AI provider (anthropic, openai, …). Stamp this on
	// every span the CLI emits, and continue stamping
	// GenAISystem until the downstream consumers are cut over.
	GenAIProviderName = "gen_ai.provider.name"

	// GenAISystemOpenAI represents OpenAI system
	GenAISystemOpenAI = "openai"
	// GenAISystemAnthropic represents Anthropic system
	GenAISystemAnthropic = "anthropic"
	// GenAISystemVLLM represents vLLM system
	GenAISystemVLLM = "vllm"
)

System / Provider Identifiers.

OTel GenAI renamed the long-standing `gen_ai.system` attribute to `gen_ai.provider.name` (see GenAI semconv 1.36+). The constant for the legacy key is preserved so we can dual-stamp during the transition window without breaking existing dashboards.

const (
	// GenAIRequestModel is the model name being requested
	GenAIRequestModel = "gen_ai.request.model"
	// GenAIRequestTemperature is the temperature parameter
	GenAIRequestTemperature = "gen_ai.request.temperature"
	// GenAIRequestTopP is the top_p parameter
	GenAIRequestTopP = "gen_ai.request.top_p"
	// GenAIRequestTopK is the top_k parameter
	GenAIRequestTopK = "gen_ai.request.top_k"
	// GenAIRequestMaxTokens is the maximum tokens requested
	GenAIRequestMaxTokens = "gen_ai.request.max_tokens"
	// GenAIRequestFrequencyPenalty is the frequency penalty parameter
	GenAIRequestFrequencyPenalty = "gen_ai.request.frequency_penalty"
	// GenAIRequestPresencePenalty is the presence penalty parameter
	GenAIRequestPresencePenalty = "gen_ai.request.presence_penalty"
	// GenAIRequestStopSequences are the stop sequences
	GenAIRequestStopSequences = "gen_ai.request.stop_sequences"
	// GenAIRequestSeed is the seed for deterministic generation
	GenAIRequestSeed = "gen_ai.request.seed"
	// GenAIRequestChoiceCount is the number of choices requested
	GenAIRequestChoiceCount = "gen_ai.request.choice_count"
	// GenAIRequestIsStream indicates whether the request uses streaming
	GenAIRequestIsStream = "gen_ai.request.is_stream"
	// GenAIRequestUser is the end-user identifier for the request
	GenAIRequestUser = "gen_ai.request.user"
)

Request Attributes

const (
	// GenAIResponseModel is the actual model that generated the response
	GenAIResponseModel = "gen_ai.response.model"
	// GenAIResponseID is the unique identifier for the response
	GenAIResponseID = "gen_ai.response.id"
	// GenAIResponseFinishReasons are the reasons why generation stopped
	GenAIResponseFinishReasons = "gen_ai.response.finish_reasons"
	// GenAIResponseChoiceCount is the number of choices in response
	GenAIResponseChoiceCount = "gen_ai.response.choice_count"
)

Response Attributes

const (
	// GenAIUsageInputTokens is the number of input tokens
	GenAIUsageInputTokens = "gen_ai.usage.input_tokens"
	// GenAIUsageOutputTokens is the number of output tokens
	GenAIUsageOutputTokens = "gen_ai.usage.output_tokens"
	// GenAIUsageTotalTokens is the total number of tokens
	GenAIUsageTotalTokens = "gen_ai.usage.total_tokens"
	// GenAIUsageCost is the estimated cost of the operation
	GenAIUsageCost = "gen_ai.usage.cost"
	// GenAITokenType distinguishes input vs output on token usage metrics
	GenAITokenType = "gen_ai.token.type"
)

Usage Attributes

const (
	// GenAIUsageCompletionTokensDetailsAudio tracks audio output tokens
	GenAIUsageCompletionTokensDetailsAudio = "gen_ai.usage.completion_tokens_details.audio"
	// GenAIUsageCompletionTokensDetailsReasoning tracks reasoning tokens
	// (legacy; prefer GenAIUsageReasoningTokens)
	GenAIUsageCompletionTokensDetailsReasoning = "gen_ai.usage.completion_tokens_details.reasoning"
	// GenAIUsagePromptTokensDetailsCacheRead tracks cached tokens read
	// (legacy; prefer GenAIUsageCacheReadInputTokens)
	GenAIUsagePromptTokensDetailsCacheRead = "gen_ai.usage.prompt_tokens_details.cache_read"
	// GenAIUsagePromptTokensDetailsCacheWrite tracks cached tokens written
	// (legacy; prefer GenAIUsageCacheCreationInputTokens)
	GenAIUsagePromptTokensDetailsCacheWrite = "gen_ai.usage.prompt_tokens_details.cache_write"
)

Token Details (OpenAI specific - legacy).

OTel GenAI introduced first-class cache / reasoning token attributes in 1.36+. The new shape lives below in `GenAIUsageCache*` and `GenAIUsageReasoningTokens`; the `*_details.*` constants here are kept only to interoperate with older receivers still keying off the OpenAI-shaped names.

const (
	// GenAIUsageCacheReadInputTokens is the cumulative count of input
	// tokens that hit the provider's prompt cache for the request.
	GenAIUsageCacheReadInputTokens = "gen_ai.usage.cache.read_input_tokens"
	// GenAIUsageCacheCreationInputTokens is the count of input tokens
	// the provider stored into a fresh cache entry on this request.
	GenAIUsageCacheCreationInputTokens = "gen_ai.usage.cache.creation_input_tokens"
	// GenAIUsageReasoningTokens is the count of reasoning / thinking
	// tokens the model spent on the response (Anthropic's "thinking"
	// budget, OpenAI's o*-series reasoning).
	GenAIUsageReasoningTokens = "gen_ai.usage.reasoning_tokens"
)

Token Details (OTel 1.36+ canonical names).

const (
	// GenAIPrompt is the legacy prompt attribute
	GenAIPrompt = "gen_ai.prompt"
	// GenAICompletion is the legacy completion attribute
	GenAICompletion = "gen_ai.completion"
	// GenAIInputMessages are the structured input messages
	GenAIInputMessages = "gen_ai.input.messages"
	// GenAIOutputMessages are the structured output messages
	GenAIOutputMessages = "gen_ai.output.messages"
	// GenAISystemInstructions are system-level instructions
	GenAISystemInstructions = "gen_ai.system_instructions"
)

Message Attributes

const (
	// GenAIToolDefinitions are the tool/function definitions provided
	GenAIToolDefinitions = "gen_ai.tool.definitions"
	// GenAIToolCalls are the tool/function calls made
	GenAIToolCalls = "gen_ai.tool.calls"
	// GenAIToolType is the type of tool (e.g. "function")
	GenAIToolType = "gen_ai.tool.type"
	// GenAIToolName is the comma-joined list of tool names called by the model
	GenAIToolName = "gen_ai.tool.name"
	// GenAIToolCallID is the comma-joined list of tool call IDs from the model response
	GenAIToolCallID = "gen_ai.tool.call.id"
	// GenAIToolCallArguments is the array of JSON argument strings from model tool calls
	GenAIToolCallArguments = "gen_ai.tool.call.arguments"
)

Tool/Function Attributes

const (
	// GenAIOpenAIAssistantID is the OpenAI assistant ID
	GenAIOpenAIAssistantID = "gen_ai.openai.assistant.id"
	// GenAIOpenAIThreadID is the OpenAI thread ID
	GenAIOpenAIThreadID = "gen_ai.openai.thread.id"
	// GenAIOpenAIRunID is the OpenAI run ID
	GenAIOpenAIRunID = "gen_ai.openai.run.id"
	// GenAIOpenAIRequestServiceTier is the requested service tier
	GenAIOpenAIRequestServiceTier = "gen_ai.openai.request.service_tier"
	// GenAIOpenAIResponseServiceTier is the actual service tier used
	GenAIOpenAIResponseServiceTier = "gen_ai.openai.response.service_tier"
	// GenAIOpenAIResponseSystemFingerprint is the system fingerprint
	GenAIOpenAIResponseSystemFingerprint = "gen_ai.openai.response.system_fingerprint"
)

OpenAI Specific Attributes

const (
	// GenAIOutputType is the requested content type
	GenAIOutputType = "gen_ai.output.type"
	// GenAIOutputTypeText represents text output
	GenAIOutputTypeText = "text"
	// GenAIOutputTypeJSON represents JSON output
	GenAIOutputTypeJSON = "json_object"
)

Output Type

const (
	// ServerAddress is the server address
	ServerAddress = "server.address"
	// ServerPort is the server port
	ServerPort = "server.port"
)

Server Attributes

const (
	// GenAIClientInferenceOperationDetails is the event name for operation details
	GenAIClientInferenceOperationDetails = "gen_ai.client.inference.operation.details"
	// GenAIUserMessage is the event name for user messages
	GenAIUserMessage = "gen_ai.user.message"
	// GenAISystemMessage is the event name for system messages
	GenAISystemMessage = "gen_ai.system.message"
	// GenAIAssistantMessage is the event name for assistant messages
	GenAIAssistantMessage = "gen_ai.assistant.message"
	// GenAIToolMessage is the event name for tool messages
	GenAIToolMessage = "gen_ai.tools.message"
	// GenAIChoice is the event name for choice details
	GenAIChoice = "gen_ai.choice"
)

Event Names

const (
	// GenAIClientTokenUsage tracks token usage
	GenAIClientTokenUsage = "gen_ai.client.token.usage"
	// GenAIClientOperationDuration tracks operation duration
	GenAIClientOperationDuration = "gen_ai.client.operation.duration"
	// GenAIServerRequestDuration tracks server request duration
	GenAIServerRequestDuration = "gen_ai.server.request.duration"
	// GenAIServerTimePerOutputToken tracks time between tokens
	GenAIServerTimePerOutputToken = "gen_ai.server.time_per_output_token"
	// GenAIServerTimeToFirstToken tracks time to first token
	GenAIServerTimeToFirstToken = "gen_ai.server.time_to_first_token"
	// GenAIClientOperationTimeToFirstChunk tracks client-side time to first chunk in streaming
	GenAIClientOperationTimeToFirstChunk = "gen_ai.client.operation.time_to_first_chunk"
	// GenAIClientOperationTimePerOutputChunk tracks per-chunk output token latency observations in streaming
	GenAIClientOperationTimePerOutputChunk = "gen_ai.client.operation.time_per_output_chunk"
)

Metric Names

const (
	// Shield360Environment is the deployment environment
	Shield360Environment = "shield360.environment"
	// Shield360ApplicationName is the application name
	Shield360ApplicationName = "shield360.application.name"
	// Shield360SDKVersion is the SDK version
	Shield360SDKVersion = "shield360.sdk.version"
)

Environment Attributes

const CodingAgentSchemaVersion = "1"

Schema version of the coding_agent.* wire format. Bump on breaking changes.

const (
	// CodingAgentVCSDirty indicates the working tree has uncommitted changes
	// when the agent started. Boolean serialized as "true"/"false".
	CodingAgentVCSDirty = "coding_agent.vcs.dirty"
)

VCS bridging — repo / branch / commit live under OTel's standard `vcs.*` attributes (see Reuse note at top of file), stamped on the session root from local git context by `cli/internal/coding/git`. The constants below cover what OTel doesn't define.

const (
	// ErrorType describes the error type
	ErrorType = "error.type"
)

Error Attributes

const (
	// GenAIConversationID identifies a conversation/session
	GenAIConversationID = "gen_ai.conversation.id"
)

Conversation Attributes

Functions

func SetBoolAttribute

func SetBoolAttribute(span trace.Span, key string, value bool)

SetBoolAttribute sets a bool attribute on a span

func SetFloat64Attribute

func SetFloat64Attribute(span trace.Span, key string, value float64)

SetFloat64Attribute sets a float64 attribute on a span

func SetInt64Attribute

func SetInt64Attribute(span trace.Span, key string, value int64)

SetInt64Attribute sets an int64 attribute on a span

func SetIntAttribute

func SetIntAttribute(span trace.Span, key string, value int)

SetIntAttribute sets an int attribute on a span

func SetJSONAttribute

func SetJSONAttribute(span trace.Span, key string, value interface{}) error

SetJSONAttribute sets a JSON-encoded attribute on a span

func SetMessagesAttribute

func SetMessagesAttribute(span trace.Span, key string, messages []Message) error

SetMessagesAttribute sets structured messages as JSON attribute

func SetStringAttribute

func SetStringAttribute(span trace.Span, key, value string)

SetStringAttribute sets a string attribute on a span if value is not empty

func SetStringSliceAttribute

func SetStringSliceAttribute(span trace.Span, key string, values []string)

SetStringSliceAttribute sets a string slice attribute on a span if not empty

func SetToolCallsAttribute

func SetToolCallsAttribute(span trace.Span, key string, toolCalls []ToolCall) error

SetToolCallsAttribute sets tool calls as JSON attribute

func SetToolDefinitionsAttribute

func SetToolDefinitionsAttribute(span trace.Span, key string, tools []ToolDefinition) error

SetToolDefinitionsAttribute sets tool definitions as JSON attribute

Types

type AttributeBuilder

type AttributeBuilder struct {
	// contains filtered or unexported fields
}

AttributeBuilder provides a fluent interface for building attributes

func NewAttributeBuilder

func NewAttributeBuilder() *AttributeBuilder

NewAttributeBuilder creates a new attribute builder

func (*AttributeBuilder) Bool

func (ab *AttributeBuilder) Bool(key string, value bool) *AttributeBuilder

Bool adds a bool attribute

func (*AttributeBuilder) Build

func (ab *AttributeBuilder) Build() []attribute.KeyValue

Build returns the built attributes

func (*AttributeBuilder) Float64

func (ab *AttributeBuilder) Float64(key string, value float64) *AttributeBuilder

Float64 adds a float64 attribute

func (*AttributeBuilder) Int

func (ab *AttributeBuilder) Int(key string, value int) *AttributeBuilder

Int adds an int attribute

func (*AttributeBuilder) Int64

func (ab *AttributeBuilder) Int64(key string, value int64) *AttributeBuilder

Int64 adds an int64 attribute

func (*AttributeBuilder) SetAttributes

func (ab *AttributeBuilder) SetAttributes(span trace.Span)

SetAttributes sets all attributes on a span

func (*AttributeBuilder) String

func (ab *AttributeBuilder) String(key, value string) *AttributeBuilder

String adds a string attribute

func (*AttributeBuilder) StringSlice

func (ab *AttributeBuilder) StringSlice(key string, values []string) *AttributeBuilder

StringSlice adds a string slice attribute

type Message

type Message struct {
	Role    string        `json:"role"`
	Content string        `json:"content,omitempty"`
	Parts   []MessagePart `json:"parts,omitempty"`
}

Message represents a chat message structure

type MessagePart

type MessagePart struct {
	Type    string `json:"type"`
	Content string `json:"content,omitempty"`
	Text    string `json:"text,omitempty"`
}

MessagePart represents a part of a message (text, image, etc.)

type ToolCall

type ToolCall struct {
	ID       string `json:"id,omitempty"`
	Type     string `json:"type"`
	Function struct {
		Name      string `json:"name"`
		Arguments string `json:"arguments"`
	} `json:"function,omitempty"`
}

ToolCall represents a tool/function call

type ToolDefinition

type ToolDefinition struct {
	Type     string `json:"type"`
	Function struct {
		Name        string                 `json:"name"`
		Description string                 `json:"description,omitempty"`
		Parameters  map[string]interface{} `json:"parameters,omitempty"`
	} `json:"function,omitempty"`
}

ToolDefinition represents a tool/function definition