diff --git a/csharp/src/FIInstrumentation/SemanticConventions.cs b/csharp/src/FIInstrumentation/SemanticConventions.cs index 4955e30c2..5250ef965 100644 --- a/csharp/src/FIInstrumentation/SemanticConventions.cs +++ b/csharp/src/FIInstrumentation/SemanticConventions.cs @@ -6,6 +6,89 @@ namespace FIInstrumentation; /// public static class SemanticConventions { + // Coding-agent usage and provenance. + /// Source tool name on TOOL spans; do not rely on the display span name. + public const string ToolName = "tool.name"; + + /// Scope of canonical usage: request, attempt, turn or unknown. A turn aggregate is not a measured individual request. + public const string FiUsageScope = "fi.usage.scope"; + + /// Use none for non-additive summaries and additive for the sole owner of canonical usage. Never duplicate canonical tokens or cost on summaries: older aggregate readers sum all span kinds. + public const string FiUsageContribution = "fi.usage.contribution"; + + /// Cost provenance understood by Future AGI: provider_reported, estimated or unknown. Unknown must not be represented by an invented zero. + public const string FiCostKind = "fi.cost.kind"; + + /// Evidence fidelity: native-request, reconstructed-message, aggregate-turn or unknown. Only source-observed requests/messages may be LLM spans. + public const string FiAgentFidelity = "fi.agent.fidelity"; + + /// Timing provenance: source, reconstructed or observed-event. Reconstructed message timing is not measured request latency or TTFT. + public const string FiAgentTiming = "fi.agent.timing"; + + /// Terminal outcome: success, error, interrupted or incomplete; missing stop events are incomplete, not success. + public const string FiAgentOutcome = "fi.agent.outcome"; + + /// Boolean provenance flag for canonical usage ownership; not itself a backend aggregation gate. Request/attempt plans count each observed model operation once. For turn-only totals, place canonical usage exactly once on the last source-observed generation (marked scope=turn), or the AGENT root if there is no generation. Keep all other spans summary-only; never fabricate a model request. + public const string FiAgentUsageAdditive = "fi.agent.usage.additive"; + + /// One immutable plan per turn: request, attempt, turn or unknown. Never mix per-request counters and overlapping turn totals; unknown plans remain summary-only. + public const string FiAgentUsagePlan = "fi.agent.usage.plan"; + + /// Boolean: source input count already includes cache reads/writes. Normalize input once; cache detail counters are subsets, not additional total tokens. + public const string FiAgentUsageCacheInInput = "fi.agent.usage.cache_in_input"; + + /// Boolean: source output count already includes reasoning. Normalize output once; reasoning is a subset, not extra total tokens. + public const string FiAgentUsageReasoningInOutput = "fi.agent.usage.reasoning_in_output"; + + /// Source of the cost, for example reported or host-price-table; independent of whether this span contributes to totals. + public const string FiAgentCostSource = "fi.agent.cost.source"; + + /// Identifier/version of the estimator or price table for estimated costs; omit for reported costs. Never include credentials. + public const string FiAgentCostEstimator = "fi.agent.cost.estimator"; + + /// Bounded diagnostic code for missing evidence, for example MISSING_PARENT, MISSING_CHILD_STOP or UNRESOLVED_USAGE; not raw error content. + public const string FiAgentGap = "fi.agent.gap"; + + /// Versioned transport contract identifier; not an endpoint URL or credential. + public const string FiAgentTransport = "fi.agent.transport"; + + /// Opaque integration correlation identifier; not a substitute for a source-provided tool_call.id. + public const string FiAgentSourceCallId = "fi.agent.source_call_id"; + + /// Non-additive normalized input token summary; never summed into canonical usage. + public const string FiAgentSummaryInput = "fi.agent.summary.input"; + + /// Non-additive normalized output token summary; never summed into canonical usage. + public const string FiAgentSummaryOutput = "fi.agent.summary.output"; + + /// Non-additive input plus output token summary; never summed into canonical usage. + public const string FiAgentSummaryTotal = "fi.agent.summary.total"; + + /// Non-additive cache-read token summary, a subset of normalized input. + public const string FiAgentSummaryCacheRead = "fi.agent.summary.cache_read"; + + /// Non-additive cache-write token summary, a subset of normalized input. + public const string FiAgentSummaryCacheWrite = "fi.agent.summary.cache_write"; + + /// Non-additive reasoning token summary, a subset of normalized output. + public const string FiAgentSummaryReasoning = "fi.agent.summary.reasoning"; + + /// Non-additive cost summary in USD; never place this amount in canonical cost as well unless this span owns the usage. + public const string FiAgentSummaryCostUsd = "fi.agent.summary.cost_usd"; + + /// JSON-encoded array of configured bounded tags, subject to the integration privacy policy. + public const string FiAgentTags = "fi.agent.tags"; + + /// Agent lifecycle event type, for example compaction; not a model invocation. + public const string FiAgentEvent = "fi.agent.event"; + + /// Source input completeness, for example partial; do not present an excerpt as the full model input. + public const string FiAgentInputCompleteness = "fi.agent.input.completeness"; + + /// Provenance of captured content, for example a source transcript; not evidence of native request capture. + public const string FiAgentContentSource = "fi.agent.content.source"; + + // ── FI Span Kind ───────────────────────────────────────────────── public const string FiSpanKind = "fi.span.kind"; @@ -126,6 +209,7 @@ public static class SemanticConventions // ── GenAI Performance / Streaming ──────────────────────────────── public const string GenAiClientOperationDuration = "gen_ai.client.operation.duration"; + /// Measured time to first token in milliseconds for the Future AGI span attribute consumer. Not the OTel histogram unit (seconds). Convert seconds to milliseconds before emission; omit for reconstructed timing. The current gateway seconds writer is inconsistent with the dashboard and requires a separate migration. public const string GenAiServerTimeToFirstToken = "gen_ai.server.time_to_first_token"; public const string GenAiServerTimePerOutputToken = "gen_ai.server.time_per_output_token"; public const string GenAiServerQueueTime = "gen_ai.server.queue_time"; diff --git a/csharp/tests/FIInstrumentation.Tests/AgentSemanticConventionsTests.cs b/csharp/tests/FIInstrumentation.Tests/AgentSemanticConventionsTests.cs new file mode 100644 index 000000000..ec458a514 --- /dev/null +++ b/csharp/tests/FIInstrumentation.Tests/AgentSemanticConventionsTests.cs @@ -0,0 +1,41 @@ +namespace FIInstrumentation.Tests; + +public class AgentSemanticConventionsTests +{ + [Fact] + public void CodingAgentWireContract() + { + Assert.Equal("gen_ai.cost.total", SemanticConventions.GenAiCostTotal); + Assert.Equal("gen_ai.cost.input", SemanticConventions.GenAiCostInput); + Assert.Equal("gen_ai.cost.output", SemanticConventions.GenAiCostOutput); + Assert.Equal("gen_ai.server.time_to_first_token", SemanticConventions.GenAiServerTimeToFirstToken); + Assert.Equal("tool.name", SemanticConventions.ToolName); + Assert.Equal("tool_call.id", SemanticConventions.ToolCallId); + Assert.Equal("fi.usage.scope", SemanticConventions.FiUsageScope); + Assert.Equal("fi.usage.contribution", SemanticConventions.FiUsageContribution); + Assert.Equal("fi.cost.kind", SemanticConventions.FiCostKind); + Assert.Equal("fi.agent.fidelity", SemanticConventions.FiAgentFidelity); + Assert.Equal("fi.agent.timing", SemanticConventions.FiAgentTiming); + Assert.Equal("fi.agent.outcome", SemanticConventions.FiAgentOutcome); + Assert.Equal("fi.agent.usage.additive", SemanticConventions.FiAgentUsageAdditive); + Assert.Equal("fi.agent.usage.plan", SemanticConventions.FiAgentUsagePlan); + Assert.Equal("fi.agent.usage.cache_in_input", SemanticConventions.FiAgentUsageCacheInInput); + Assert.Equal("fi.agent.usage.reasoning_in_output", SemanticConventions.FiAgentUsageReasoningInOutput); + Assert.Equal("fi.agent.cost.source", SemanticConventions.FiAgentCostSource); + Assert.Equal("fi.agent.cost.estimator", SemanticConventions.FiAgentCostEstimator); + Assert.Equal("fi.agent.gap", SemanticConventions.FiAgentGap); + Assert.Equal("fi.agent.transport", SemanticConventions.FiAgentTransport); + Assert.Equal("fi.agent.source_call_id", SemanticConventions.FiAgentSourceCallId); + Assert.Equal("fi.agent.summary.input", SemanticConventions.FiAgentSummaryInput); + Assert.Equal("fi.agent.summary.output", SemanticConventions.FiAgentSummaryOutput); + Assert.Equal("fi.agent.summary.total", SemanticConventions.FiAgentSummaryTotal); + Assert.Equal("fi.agent.summary.cache_read", SemanticConventions.FiAgentSummaryCacheRead); + Assert.Equal("fi.agent.summary.cache_write", SemanticConventions.FiAgentSummaryCacheWrite); + Assert.Equal("fi.agent.summary.reasoning", SemanticConventions.FiAgentSummaryReasoning); + Assert.Equal("fi.agent.summary.cost_usd", SemanticConventions.FiAgentSummaryCostUsd); + Assert.Equal("fi.agent.tags", SemanticConventions.FiAgentTags); + Assert.Equal("fi.agent.event", SemanticConventions.FiAgentEvent); + Assert.Equal("fi.agent.input.completeness", SemanticConventions.FiAgentInputCompleteness); + Assert.Equal("fi.agent.content.source", SemanticConventions.FiAgentContentSource); + } +} diff --git a/go/a2a/agent_semantic_conventions_test.go b/go/a2a/agent_semantic_conventions_test.go new file mode 100644 index 000000000..12b67e140 --- /dev/null +++ b/go/a2a/agent_semantic_conventions_test.go @@ -0,0 +1,44 @@ +package traceaia2a + +import "testing" + +func TestCodingAgentWireContract(t *testing.T) { + for name, pair := range map[string][2]string{ + "GenAICostTotal": {GenAICostTotal, "gen_ai.cost.total"}, + "GenAICostInput": {GenAICostInput, "gen_ai.cost.input"}, + "GenAICostOutput": {GenAICostOutput, "gen_ai.cost.output"}, + "GenAIServerTimeToFirstToken": {GenAIServerTimeToFirstToken, "gen_ai.server.time_to_first_token"}, + "ToolName": {ToolName, "tool.name"}, + "ToolCallID": {ToolCallID, "tool_call.id"}, + "FIUsageScope": {FIUsageScope, "fi.usage.scope"}, + "FIUsageContribution": {FIUsageContribution, "fi.usage.contribution"}, + "FICostKind": {FICostKind, "fi.cost.kind"}, + "FIAgentFidelity": {FIAgentFidelity, "fi.agent.fidelity"}, + "FIAgentTiming": {FIAgentTiming, "fi.agent.timing"}, + "FIAgentOutcome": {FIAgentOutcome, "fi.agent.outcome"}, + "FIAgentUsageAdditive": {FIAgentUsageAdditive, "fi.agent.usage.additive"}, + "FIAgentUsagePlan": {FIAgentUsagePlan, "fi.agent.usage.plan"}, + "FIAgentUsageCacheInInput": {FIAgentUsageCacheInInput, "fi.agent.usage.cache_in_input"}, + "FIAgentUsageReasoningInOutput": {FIAgentUsageReasoningInOutput, "fi.agent.usage.reasoning_in_output"}, + "FIAgentCostSource": {FIAgentCostSource, "fi.agent.cost.source"}, + "FIAgentCostEstimator": {FIAgentCostEstimator, "fi.agent.cost.estimator"}, + "FIAgentGap": {FIAgentGap, "fi.agent.gap"}, + "FIAgentTransport": {FIAgentTransport, "fi.agent.transport"}, + "FIAgentSourceCallID": {FIAgentSourceCallID, "fi.agent.source_call_id"}, + "FIAgentSummaryInput": {FIAgentSummaryInput, "fi.agent.summary.input"}, + "FIAgentSummaryOutput": {FIAgentSummaryOutput, "fi.agent.summary.output"}, + "FIAgentSummaryTotal": {FIAgentSummaryTotal, "fi.agent.summary.total"}, + "FIAgentSummaryCacheRead": {FIAgentSummaryCacheRead, "fi.agent.summary.cache_read"}, + "FIAgentSummaryCacheWrite": {FIAgentSummaryCacheWrite, "fi.agent.summary.cache_write"}, + "FIAgentSummaryReasoning": {FIAgentSummaryReasoning, "fi.agent.summary.reasoning"}, + "FIAgentSummaryCostUSD": {FIAgentSummaryCostUSD, "fi.agent.summary.cost_usd"}, + "FIAgentTags": {FIAgentTags, "fi.agent.tags"}, + "FIAgentEvent": {FIAgentEvent, "fi.agent.event"}, + "FIAgentInputCompleteness": {FIAgentInputCompleteness, "fi.agent.input.completeness"}, + "FIAgentContentSource": {FIAgentContentSource, "fi.agent.content.source"}, + } { + if pair[0] != pair[1] { + t.Errorf("%s = %q, want %q", name, pair[0], pair[1]) + } + } +} diff --git a/go/a2a/attributes.go b/go/a2a/attributes.go index 5aa9326dd..bfb7336d6 100644 --- a/go/a2a/attributes.go +++ b/go/a2a/attributes.go @@ -78,3 +78,71 @@ const ( OperationCancel = "a2a.cancel_task" OperationSubscribe = "a2a.subscribe_to_task" ) + +// Coding-agent usage and provenance. fi.agent.* is metadata, not an aggregation gate. +const ( + // GenAICostTotal: Total cost in USD for this additive usage owner only; omit unknown costs, preserve an explicitly reported zero. + GenAICostTotal = "gen_ai.cost.total" + // GenAICostInput: Input cost in USD for this additive usage owner only; total cost takes precedence over input plus output. + GenAICostInput = "gen_ai.cost.input" + // GenAICostOutput: Output cost in USD for this additive usage owner only; total cost takes precedence over input plus output. + GenAICostOutput = "gen_ai.cost.output" + // GenAIServerTimeToFirstToken: Measured time to first token in milliseconds for the Future AGI span attribute consumer. Not the OTel histogram unit (seconds). Convert seconds to milliseconds before emission; omit for reconstructed timing. The current gateway seconds writer is inconsistent with the dashboard and requires a separate migration. + GenAIServerTimeToFirstToken = "gen_ai.server.time_to_first_token" + // ToolName: Source tool name on TOOL spans; do not rely on the display span name. + ToolName = "tool.name" + // ToolCallID: Source tool-call identifier when available; omit rather than invent an identifier. + ToolCallID = "tool_call.id" + // FIUsageScope: Scope of canonical usage: request, attempt, turn or unknown. A turn aggregate is not a measured individual request. + FIUsageScope = "fi.usage.scope" + // FIUsageContribution: Use none for non-additive summaries and additive for the sole owner of canonical usage. Never duplicate canonical tokens or cost on summaries: older aggregate readers sum all span kinds. + FIUsageContribution = "fi.usage.contribution" + // FICostKind: Cost provenance understood by Future AGI: provider_reported, estimated or unknown. Unknown must not be represented by an invented zero. + FICostKind = "fi.cost.kind" + // FIAgentFidelity: Evidence fidelity: native-request, reconstructed-message, aggregate-turn or unknown. Only source-observed requests/messages may be LLM spans. + FIAgentFidelity = "fi.agent.fidelity" + // FIAgentTiming: Timing provenance: source, reconstructed or observed-event. Reconstructed message timing is not measured request latency or TTFT. + FIAgentTiming = "fi.agent.timing" + // FIAgentOutcome: Terminal outcome: success, error, interrupted or incomplete; missing stop events are incomplete, not success. + FIAgentOutcome = "fi.agent.outcome" + // FIAgentUsageAdditive: Boolean provenance flag for canonical usage ownership; not itself a backend aggregation gate. Request/attempt plans count each observed model operation once. For turn-only totals, place canonical usage exactly once on the last source-observed generation (marked scope=turn), or the AGENT root if there is no generation. Keep all other spans summary-only; never fabricate a model request. + FIAgentUsageAdditive = "fi.agent.usage.additive" + // FIAgentUsagePlan: One immutable plan per turn: request, attempt, turn or unknown. Never mix per-request counters and overlapping turn totals; unknown plans remain summary-only. + FIAgentUsagePlan = "fi.agent.usage.plan" + // FIAgentUsageCacheInInput: Boolean: source input count already includes cache reads/writes. Normalize input once; cache detail counters are subsets, not additional total tokens. + FIAgentUsageCacheInInput = "fi.agent.usage.cache_in_input" + // FIAgentUsageReasoningInOutput: Boolean: source output count already includes reasoning. Normalize output once; reasoning is a subset, not extra total tokens. + FIAgentUsageReasoningInOutput = "fi.agent.usage.reasoning_in_output" + // FIAgentCostSource: Source of the cost, for example reported or host-price-table; independent of whether this span contributes to totals. + FIAgentCostSource = "fi.agent.cost.source" + // FIAgentCostEstimator: Identifier/version of the estimator or price table for estimated costs; omit for reported costs. Never include credentials. + FIAgentCostEstimator = "fi.agent.cost.estimator" + // FIAgentGap: Bounded diagnostic code for missing evidence, for example MISSING_PARENT, MISSING_CHILD_STOP or UNRESOLVED_USAGE; not raw error content. + FIAgentGap = "fi.agent.gap" + // FIAgentTransport: Versioned transport contract identifier; not an endpoint URL or credential. + FIAgentTransport = "fi.agent.transport" + // FIAgentSourceCallID: Opaque integration correlation identifier; not a substitute for a source-provided tool_call.id. + FIAgentSourceCallID = "fi.agent.source_call_id" + // FIAgentSummaryInput: Non-additive normalized input token summary; never summed into canonical usage. + FIAgentSummaryInput = "fi.agent.summary.input" + // FIAgentSummaryOutput: Non-additive normalized output token summary; never summed into canonical usage. + FIAgentSummaryOutput = "fi.agent.summary.output" + // FIAgentSummaryTotal: Non-additive input plus output token summary; never summed into canonical usage. + FIAgentSummaryTotal = "fi.agent.summary.total" + // FIAgentSummaryCacheRead: Non-additive cache-read token summary, a subset of normalized input. + FIAgentSummaryCacheRead = "fi.agent.summary.cache_read" + // FIAgentSummaryCacheWrite: Non-additive cache-write token summary, a subset of normalized input. + FIAgentSummaryCacheWrite = "fi.agent.summary.cache_write" + // FIAgentSummaryReasoning: Non-additive reasoning token summary, a subset of normalized output. + FIAgentSummaryReasoning = "fi.agent.summary.reasoning" + // FIAgentSummaryCostUSD: Non-additive cost summary in USD; never place this amount in canonical cost as well unless this span owns the usage. + FIAgentSummaryCostUSD = "fi.agent.summary.cost_usd" + // FIAgentTags: JSON-encoded array of configured bounded tags, subject to the integration privacy policy. + FIAgentTags = "fi.agent.tags" + // FIAgentEvent: Agent lifecycle event type, for example compaction; not a model invocation. + FIAgentEvent = "fi.agent.event" + // FIAgentInputCompleteness: Source input completeness, for example partial; do not present an excerpt as the full model input. + FIAgentInputCompleteness = "fi.agent.input.completeness" + // FIAgentContentSource: Provenance of captured content, for example a source transcript; not evidence of native request capture. + FIAgentContentSource = "fi.agent.content.source" +) diff --git a/go/anthropic/agent_semantic_conventions_test.go b/go/anthropic/agent_semantic_conventions_test.go new file mode 100644 index 000000000..21274b66c --- /dev/null +++ b/go/anthropic/agent_semantic_conventions_test.go @@ -0,0 +1,44 @@ +package traceaianthropic + +import "testing" + +func TestCodingAgentWireContract(t *testing.T) { + for name, pair := range map[string][2]string{ + "GenAICostTotal": {GenAICostTotal, "gen_ai.cost.total"}, + "GenAICostInput": {GenAICostInput, "gen_ai.cost.input"}, + "GenAICostOutput": {GenAICostOutput, "gen_ai.cost.output"}, + "GenAIServerTimeToFirstToken": {GenAIServerTimeToFirstToken, "gen_ai.server.time_to_first_token"}, + "ToolName": {ToolName, "tool.name"}, + "ToolCallID": {ToolCallID, "tool_call.id"}, + "FIUsageScope": {FIUsageScope, "fi.usage.scope"}, + "FIUsageContribution": {FIUsageContribution, "fi.usage.contribution"}, + "FICostKind": {FICostKind, "fi.cost.kind"}, + "FIAgentFidelity": {FIAgentFidelity, "fi.agent.fidelity"}, + "FIAgentTiming": {FIAgentTiming, "fi.agent.timing"}, + "FIAgentOutcome": {FIAgentOutcome, "fi.agent.outcome"}, + "FIAgentUsageAdditive": {FIAgentUsageAdditive, "fi.agent.usage.additive"}, + "FIAgentUsagePlan": {FIAgentUsagePlan, "fi.agent.usage.plan"}, + "FIAgentUsageCacheInInput": {FIAgentUsageCacheInInput, "fi.agent.usage.cache_in_input"}, + "FIAgentUsageReasoningInOutput": {FIAgentUsageReasoningInOutput, "fi.agent.usage.reasoning_in_output"}, + "FIAgentCostSource": {FIAgentCostSource, "fi.agent.cost.source"}, + "FIAgentCostEstimator": {FIAgentCostEstimator, "fi.agent.cost.estimator"}, + "FIAgentGap": {FIAgentGap, "fi.agent.gap"}, + "FIAgentTransport": {FIAgentTransport, "fi.agent.transport"}, + "FIAgentSourceCallID": {FIAgentSourceCallID, "fi.agent.source_call_id"}, + "FIAgentSummaryInput": {FIAgentSummaryInput, "fi.agent.summary.input"}, + "FIAgentSummaryOutput": {FIAgentSummaryOutput, "fi.agent.summary.output"}, + "FIAgentSummaryTotal": {FIAgentSummaryTotal, "fi.agent.summary.total"}, + "FIAgentSummaryCacheRead": {FIAgentSummaryCacheRead, "fi.agent.summary.cache_read"}, + "FIAgentSummaryCacheWrite": {FIAgentSummaryCacheWrite, "fi.agent.summary.cache_write"}, + "FIAgentSummaryReasoning": {FIAgentSummaryReasoning, "fi.agent.summary.reasoning"}, + "FIAgentSummaryCostUSD": {FIAgentSummaryCostUSD, "fi.agent.summary.cost_usd"}, + "FIAgentTags": {FIAgentTags, "fi.agent.tags"}, + "FIAgentEvent": {FIAgentEvent, "fi.agent.event"}, + "FIAgentInputCompleteness": {FIAgentInputCompleteness, "fi.agent.input.completeness"}, + "FIAgentContentSource": {FIAgentContentSource, "fi.agent.content.source"}, + } { + if pair[0] != pair[1] { + t.Errorf("%s = %q, want %q", name, pair[0], pair[1]) + } + } +} diff --git a/go/anthropic/attributes.go b/go/anthropic/attributes.go index 28e578439..78a4742d4 100644 --- a/go/anthropic/attributes.go +++ b/go/anthropic/attributes.go @@ -60,3 +60,71 @@ const ( redactedValue = "__REDACTED__" errorTypeCancel = "canceled" ) + +// Coding-agent usage and provenance. fi.agent.* is metadata, not an aggregation gate. +const ( + // GenAICostTotal: Total cost in USD for this additive usage owner only; omit unknown costs, preserve an explicitly reported zero. + GenAICostTotal = "gen_ai.cost.total" + // GenAICostInput: Input cost in USD for this additive usage owner only; total cost takes precedence over input plus output. + GenAICostInput = "gen_ai.cost.input" + // GenAICostOutput: Output cost in USD for this additive usage owner only; total cost takes precedence over input plus output. + GenAICostOutput = "gen_ai.cost.output" + // GenAIServerTimeToFirstToken: Measured time to first token in milliseconds for the Future AGI span attribute consumer. Not the OTel histogram unit (seconds). Convert seconds to milliseconds before emission; omit for reconstructed timing. The current gateway seconds writer is inconsistent with the dashboard and requires a separate migration. + GenAIServerTimeToFirstToken = "gen_ai.server.time_to_first_token" + // ToolName: Source tool name on TOOL spans; do not rely on the display span name. + ToolName = "tool.name" + // ToolCallID: Source tool-call identifier when available; omit rather than invent an identifier. + ToolCallID = "tool_call.id" + // FIUsageScope: Scope of canonical usage: request, attempt, turn or unknown. A turn aggregate is not a measured individual request. + FIUsageScope = "fi.usage.scope" + // FIUsageContribution: Use none for non-additive summaries and additive for the sole owner of canonical usage. Never duplicate canonical tokens or cost on summaries: older aggregate readers sum all span kinds. + FIUsageContribution = "fi.usage.contribution" + // FICostKind: Cost provenance understood by Future AGI: provider_reported, estimated or unknown. Unknown must not be represented by an invented zero. + FICostKind = "fi.cost.kind" + // FIAgentFidelity: Evidence fidelity: native-request, reconstructed-message, aggregate-turn or unknown. Only source-observed requests/messages may be LLM spans. + FIAgentFidelity = "fi.agent.fidelity" + // FIAgentTiming: Timing provenance: source, reconstructed or observed-event. Reconstructed message timing is not measured request latency or TTFT. + FIAgentTiming = "fi.agent.timing" + // FIAgentOutcome: Terminal outcome: success, error, interrupted or incomplete; missing stop events are incomplete, not success. + FIAgentOutcome = "fi.agent.outcome" + // FIAgentUsageAdditive: Boolean provenance flag for canonical usage ownership; not itself a backend aggregation gate. Request/attempt plans count each observed model operation once. For turn-only totals, place canonical usage exactly once on the last source-observed generation (marked scope=turn), or the AGENT root if there is no generation. Keep all other spans summary-only; never fabricate a model request. + FIAgentUsageAdditive = "fi.agent.usage.additive" + // FIAgentUsagePlan: One immutable plan per turn: request, attempt, turn or unknown. Never mix per-request counters and overlapping turn totals; unknown plans remain summary-only. + FIAgentUsagePlan = "fi.agent.usage.plan" + // FIAgentUsageCacheInInput: Boolean: source input count already includes cache reads/writes. Normalize input once; cache detail counters are subsets, not additional total tokens. + FIAgentUsageCacheInInput = "fi.agent.usage.cache_in_input" + // FIAgentUsageReasoningInOutput: Boolean: source output count already includes reasoning. Normalize output once; reasoning is a subset, not extra total tokens. + FIAgentUsageReasoningInOutput = "fi.agent.usage.reasoning_in_output" + // FIAgentCostSource: Source of the cost, for example reported or host-price-table; independent of whether this span contributes to totals. + FIAgentCostSource = "fi.agent.cost.source" + // FIAgentCostEstimator: Identifier/version of the estimator or price table for estimated costs; omit for reported costs. Never include credentials. + FIAgentCostEstimator = "fi.agent.cost.estimator" + // FIAgentGap: Bounded diagnostic code for missing evidence, for example MISSING_PARENT, MISSING_CHILD_STOP or UNRESOLVED_USAGE; not raw error content. + FIAgentGap = "fi.agent.gap" + // FIAgentTransport: Versioned transport contract identifier; not an endpoint URL or credential. + FIAgentTransport = "fi.agent.transport" + // FIAgentSourceCallID: Opaque integration correlation identifier; not a substitute for a source-provided tool_call.id. + FIAgentSourceCallID = "fi.agent.source_call_id" + // FIAgentSummaryInput: Non-additive normalized input token summary; never summed into canonical usage. + FIAgentSummaryInput = "fi.agent.summary.input" + // FIAgentSummaryOutput: Non-additive normalized output token summary; never summed into canonical usage. + FIAgentSummaryOutput = "fi.agent.summary.output" + // FIAgentSummaryTotal: Non-additive input plus output token summary; never summed into canonical usage. + FIAgentSummaryTotal = "fi.agent.summary.total" + // FIAgentSummaryCacheRead: Non-additive cache-read token summary, a subset of normalized input. + FIAgentSummaryCacheRead = "fi.agent.summary.cache_read" + // FIAgentSummaryCacheWrite: Non-additive cache-write token summary, a subset of normalized input. + FIAgentSummaryCacheWrite = "fi.agent.summary.cache_write" + // FIAgentSummaryReasoning: Non-additive reasoning token summary, a subset of normalized output. + FIAgentSummaryReasoning = "fi.agent.summary.reasoning" + // FIAgentSummaryCostUSD: Non-additive cost summary in USD; never place this amount in canonical cost as well unless this span owns the usage. + FIAgentSummaryCostUSD = "fi.agent.summary.cost_usd" + // FIAgentTags: JSON-encoded array of configured bounded tags, subject to the integration privacy policy. + FIAgentTags = "fi.agent.tags" + // FIAgentEvent: Agent lifecycle event type, for example compaction; not a model invocation. + FIAgentEvent = "fi.agent.event" + // FIAgentInputCompleteness: Source input completeness, for example partial; do not present an excerpt as the full model input. + FIAgentInputCompleteness = "fi.agent.input.completeness" + // FIAgentContentSource: Provenance of captured content, for example a source transcript; not evidence of native request capture. + FIAgentContentSource = "fi.agent.content.source" +) diff --git a/go/eino/agent_semantic_conventions_test.go b/go/eino/agent_semantic_conventions_test.go new file mode 100644 index 000000000..269393d35 --- /dev/null +++ b/go/eino/agent_semantic_conventions_test.go @@ -0,0 +1,44 @@ +package traceaieino + +import "testing" + +func TestCodingAgentWireContract(t *testing.T) { + for name, pair := range map[string][2]string{ + "GenAICostTotal": {GenAICostTotal, "gen_ai.cost.total"}, + "GenAICostInput": {GenAICostInput, "gen_ai.cost.input"}, + "GenAICostOutput": {GenAICostOutput, "gen_ai.cost.output"}, + "GenAIServerTimeToFirstToken": {GenAIServerTimeToFirstToken, "gen_ai.server.time_to_first_token"}, + "ToolName": {ToolName, "tool.name"}, + "ToolCallID": {ToolCallID, "tool_call.id"}, + "FIUsageScope": {FIUsageScope, "fi.usage.scope"}, + "FIUsageContribution": {FIUsageContribution, "fi.usage.contribution"}, + "FICostKind": {FICostKind, "fi.cost.kind"}, + "FIAgentFidelity": {FIAgentFidelity, "fi.agent.fidelity"}, + "FIAgentTiming": {FIAgentTiming, "fi.agent.timing"}, + "FIAgentOutcome": {FIAgentOutcome, "fi.agent.outcome"}, + "FIAgentUsageAdditive": {FIAgentUsageAdditive, "fi.agent.usage.additive"}, + "FIAgentUsagePlan": {FIAgentUsagePlan, "fi.agent.usage.plan"}, + "FIAgentUsageCacheInInput": {FIAgentUsageCacheInInput, "fi.agent.usage.cache_in_input"}, + "FIAgentUsageReasoningInOutput": {FIAgentUsageReasoningInOutput, "fi.agent.usage.reasoning_in_output"}, + "FIAgentCostSource": {FIAgentCostSource, "fi.agent.cost.source"}, + "FIAgentCostEstimator": {FIAgentCostEstimator, "fi.agent.cost.estimator"}, + "FIAgentGap": {FIAgentGap, "fi.agent.gap"}, + "FIAgentTransport": {FIAgentTransport, "fi.agent.transport"}, + "FIAgentSourceCallID": {FIAgentSourceCallID, "fi.agent.source_call_id"}, + "FIAgentSummaryInput": {FIAgentSummaryInput, "fi.agent.summary.input"}, + "FIAgentSummaryOutput": {FIAgentSummaryOutput, "fi.agent.summary.output"}, + "FIAgentSummaryTotal": {FIAgentSummaryTotal, "fi.agent.summary.total"}, + "FIAgentSummaryCacheRead": {FIAgentSummaryCacheRead, "fi.agent.summary.cache_read"}, + "FIAgentSummaryCacheWrite": {FIAgentSummaryCacheWrite, "fi.agent.summary.cache_write"}, + "FIAgentSummaryReasoning": {FIAgentSummaryReasoning, "fi.agent.summary.reasoning"}, + "FIAgentSummaryCostUSD": {FIAgentSummaryCostUSD, "fi.agent.summary.cost_usd"}, + "FIAgentTags": {FIAgentTags, "fi.agent.tags"}, + "FIAgentEvent": {FIAgentEvent, "fi.agent.event"}, + "FIAgentInputCompleteness": {FIAgentInputCompleteness, "fi.agent.input.completeness"}, + "FIAgentContentSource": {FIAgentContentSource, "fi.agent.content.source"}, + } { + if pair[0] != pair[1] { + t.Errorf("%s = %q, want %q", name, pair[0], pair[1]) + } + } +} diff --git a/go/eino/attributes.go b/go/eino/attributes.go index 7e1f28e3d..4ebe7aa2b 100644 --- a/go/eino/attributes.go +++ b/go/eino/attributes.go @@ -98,3 +98,69 @@ const ( SpanKindEmbedding = "EMBEDDING" SpanKindUnknown = "UNKNOWN" ) + +// Coding-agent usage and provenance. fi.agent.* is metadata, not an aggregation gate. +const ( + // GenAICostTotal: Total cost in USD for this additive usage owner only; omit unknown costs, preserve an explicitly reported zero. + GenAICostTotal = "gen_ai.cost.total" + // GenAICostInput: Input cost in USD for this additive usage owner only; total cost takes precedence over input plus output. + GenAICostInput = "gen_ai.cost.input" + // GenAICostOutput: Output cost in USD for this additive usage owner only; total cost takes precedence over input plus output. + GenAICostOutput = "gen_ai.cost.output" + // GenAIServerTimeToFirstToken: Measured time to first token in milliseconds for the Future AGI span attribute consumer. Not the OTel histogram unit (seconds). Convert seconds to milliseconds before emission; omit for reconstructed timing. The current gateway seconds writer is inconsistent with the dashboard and requires a separate migration. + GenAIServerTimeToFirstToken = "gen_ai.server.time_to_first_token" + // ToolName: Source tool name on TOOL spans; do not rely on the display span name. + ToolName = "tool.name" + // FIUsageScope: Scope of canonical usage: request, attempt, turn or unknown. A turn aggregate is not a measured individual request. + FIUsageScope = "fi.usage.scope" + // FIUsageContribution: Use none for non-additive summaries and additive for the sole owner of canonical usage. Never duplicate canonical tokens or cost on summaries: older aggregate readers sum all span kinds. + FIUsageContribution = "fi.usage.contribution" + // FICostKind: Cost provenance understood by Future AGI: provider_reported, estimated or unknown. Unknown must not be represented by an invented zero. + FICostKind = "fi.cost.kind" + // FIAgentFidelity: Evidence fidelity: native-request, reconstructed-message, aggregate-turn or unknown. Only source-observed requests/messages may be LLM spans. + FIAgentFidelity = "fi.agent.fidelity" + // FIAgentTiming: Timing provenance: source, reconstructed or observed-event. Reconstructed message timing is not measured request latency or TTFT. + FIAgentTiming = "fi.agent.timing" + // FIAgentOutcome: Terminal outcome: success, error, interrupted or incomplete; missing stop events are incomplete, not success. + FIAgentOutcome = "fi.agent.outcome" + // FIAgentUsageAdditive: Boolean provenance flag for canonical usage ownership; not itself a backend aggregation gate. Request/attempt plans count each observed model operation once. For turn-only totals, place canonical usage exactly once on the last source-observed generation (marked scope=turn), or the AGENT root if there is no generation. Keep all other spans summary-only; never fabricate a model request. + FIAgentUsageAdditive = "fi.agent.usage.additive" + // FIAgentUsagePlan: One immutable plan per turn: request, attempt, turn or unknown. Never mix per-request counters and overlapping turn totals; unknown plans remain summary-only. + FIAgentUsagePlan = "fi.agent.usage.plan" + // FIAgentUsageCacheInInput: Boolean: source input count already includes cache reads/writes. Normalize input once; cache detail counters are subsets, not additional total tokens. + FIAgentUsageCacheInInput = "fi.agent.usage.cache_in_input" + // FIAgentUsageReasoningInOutput: Boolean: source output count already includes reasoning. Normalize output once; reasoning is a subset, not extra total tokens. + FIAgentUsageReasoningInOutput = "fi.agent.usage.reasoning_in_output" + // FIAgentCostSource: Source of the cost, for example reported or host-price-table; independent of whether this span contributes to totals. + FIAgentCostSource = "fi.agent.cost.source" + // FIAgentCostEstimator: Identifier/version of the estimator or price table for estimated costs; omit for reported costs. Never include credentials. + FIAgentCostEstimator = "fi.agent.cost.estimator" + // FIAgentGap: Bounded diagnostic code for missing evidence, for example MISSING_PARENT, MISSING_CHILD_STOP or UNRESOLVED_USAGE; not raw error content. + FIAgentGap = "fi.agent.gap" + // FIAgentTransport: Versioned transport contract identifier; not an endpoint URL or credential. + FIAgentTransport = "fi.agent.transport" + // FIAgentSourceCallID: Opaque integration correlation identifier; not a substitute for a source-provided tool_call.id. + FIAgentSourceCallID = "fi.agent.source_call_id" + // FIAgentSummaryInput: Non-additive normalized input token summary; never summed into canonical usage. + FIAgentSummaryInput = "fi.agent.summary.input" + // FIAgentSummaryOutput: Non-additive normalized output token summary; never summed into canonical usage. + FIAgentSummaryOutput = "fi.agent.summary.output" + // FIAgentSummaryTotal: Non-additive input plus output token summary; never summed into canonical usage. + FIAgentSummaryTotal = "fi.agent.summary.total" + // FIAgentSummaryCacheRead: Non-additive cache-read token summary, a subset of normalized input. + FIAgentSummaryCacheRead = "fi.agent.summary.cache_read" + // FIAgentSummaryCacheWrite: Non-additive cache-write token summary, a subset of normalized input. + FIAgentSummaryCacheWrite = "fi.agent.summary.cache_write" + // FIAgentSummaryReasoning: Non-additive reasoning token summary, a subset of normalized output. + FIAgentSummaryReasoning = "fi.agent.summary.reasoning" + // FIAgentSummaryCostUSD: Non-additive cost summary in USD; never place this amount in canonical cost as well unless this span owns the usage. + FIAgentSummaryCostUSD = "fi.agent.summary.cost_usd" + // FIAgentTags: JSON-encoded array of configured bounded tags, subject to the integration privacy policy. + FIAgentTags = "fi.agent.tags" + // FIAgentEvent: Agent lifecycle event type, for example compaction; not a model invocation. + FIAgentEvent = "fi.agent.event" + // FIAgentInputCompleteness: Source input completeness, for example partial; do not present an excerpt as the full model input. + FIAgentInputCompleteness = "fi.agent.input.completeness" + // FIAgentContentSource: Provenance of captured content, for example a source transcript; not evidence of native request capture. + FIAgentContentSource = "fi.agent.content.source" +) diff --git a/go/genai/agent_semantic_conventions_test.go b/go/genai/agent_semantic_conventions_test.go new file mode 100644 index 000000000..ea6c91add --- /dev/null +++ b/go/genai/agent_semantic_conventions_test.go @@ -0,0 +1,44 @@ +package traceaigenai + +import "testing" + +func TestCodingAgentWireContract(t *testing.T) { + for name, pair := range map[string][2]string{ + "GenAICostTotal": {GenAICostTotal, "gen_ai.cost.total"}, + "GenAICostInput": {GenAICostInput, "gen_ai.cost.input"}, + "GenAICostOutput": {GenAICostOutput, "gen_ai.cost.output"}, + "GenAIServerTimeToFirstToken": {GenAIServerTimeToFirstToken, "gen_ai.server.time_to_first_token"}, + "ToolName": {ToolName, "tool.name"}, + "ToolCallID": {ToolCallID, "tool_call.id"}, + "FIUsageScope": {FIUsageScope, "fi.usage.scope"}, + "FIUsageContribution": {FIUsageContribution, "fi.usage.contribution"}, + "FICostKind": {FICostKind, "fi.cost.kind"}, + "FIAgentFidelity": {FIAgentFidelity, "fi.agent.fidelity"}, + "FIAgentTiming": {FIAgentTiming, "fi.agent.timing"}, + "FIAgentOutcome": {FIAgentOutcome, "fi.agent.outcome"}, + "FIAgentUsageAdditive": {FIAgentUsageAdditive, "fi.agent.usage.additive"}, + "FIAgentUsagePlan": {FIAgentUsagePlan, "fi.agent.usage.plan"}, + "FIAgentUsageCacheInInput": {FIAgentUsageCacheInInput, "fi.agent.usage.cache_in_input"}, + "FIAgentUsageReasoningInOutput": {FIAgentUsageReasoningInOutput, "fi.agent.usage.reasoning_in_output"}, + "FIAgentCostSource": {FIAgentCostSource, "fi.agent.cost.source"}, + "FIAgentCostEstimator": {FIAgentCostEstimator, "fi.agent.cost.estimator"}, + "FIAgentGap": {FIAgentGap, "fi.agent.gap"}, + "FIAgentTransport": {FIAgentTransport, "fi.agent.transport"}, + "FIAgentSourceCallID": {FIAgentSourceCallID, "fi.agent.source_call_id"}, + "FIAgentSummaryInput": {FIAgentSummaryInput, "fi.agent.summary.input"}, + "FIAgentSummaryOutput": {FIAgentSummaryOutput, "fi.agent.summary.output"}, + "FIAgentSummaryTotal": {FIAgentSummaryTotal, "fi.agent.summary.total"}, + "FIAgentSummaryCacheRead": {FIAgentSummaryCacheRead, "fi.agent.summary.cache_read"}, + "FIAgentSummaryCacheWrite": {FIAgentSummaryCacheWrite, "fi.agent.summary.cache_write"}, + "FIAgentSummaryReasoning": {FIAgentSummaryReasoning, "fi.agent.summary.reasoning"}, + "FIAgentSummaryCostUSD": {FIAgentSummaryCostUSD, "fi.agent.summary.cost_usd"}, + "FIAgentTags": {FIAgentTags, "fi.agent.tags"}, + "FIAgentEvent": {FIAgentEvent, "fi.agent.event"}, + "FIAgentInputCompleteness": {FIAgentInputCompleteness, "fi.agent.input.completeness"}, + "FIAgentContentSource": {FIAgentContentSource, "fi.agent.content.source"}, + } { + if pair[0] != pair[1] { + t.Errorf("%s = %q, want %q", name, pair[0], pair[1]) + } + } +} diff --git a/go/genai/attributes.go b/go/genai/attributes.go index 345046f23..6223654b6 100644 --- a/go/genai/attributes.go +++ b/go/genai/attributes.go @@ -110,3 +110,69 @@ const ( // (Python) and traceai-java-google-genai write. ProviderGoogle = "google" ) + +// Coding-agent usage and provenance. fi.agent.* is metadata, not an aggregation gate. +const ( + // GenAICostTotal: Total cost in USD for this additive usage owner only; omit unknown costs, preserve an explicitly reported zero. + GenAICostTotal = "gen_ai.cost.total" + // GenAICostInput: Input cost in USD for this additive usage owner only; total cost takes precedence over input plus output. + GenAICostInput = "gen_ai.cost.input" + // GenAICostOutput: Output cost in USD for this additive usage owner only; total cost takes precedence over input plus output. + GenAICostOutput = "gen_ai.cost.output" + // GenAIServerTimeToFirstToken: Measured time to first token in milliseconds for the Future AGI span attribute consumer. Not the OTel histogram unit (seconds). Convert seconds to milliseconds before emission; omit for reconstructed timing. The current gateway seconds writer is inconsistent with the dashboard and requires a separate migration. + GenAIServerTimeToFirstToken = "gen_ai.server.time_to_first_token" + // ToolName: Source tool name on TOOL spans; do not rely on the display span name. + ToolName = "tool.name" + // FIUsageScope: Scope of canonical usage: request, attempt, turn or unknown. A turn aggregate is not a measured individual request. + FIUsageScope = "fi.usage.scope" + // FIUsageContribution: Use none for non-additive summaries and additive for the sole owner of canonical usage. Never duplicate canonical tokens or cost on summaries: older aggregate readers sum all span kinds. + FIUsageContribution = "fi.usage.contribution" + // FICostKind: Cost provenance understood by Future AGI: provider_reported, estimated or unknown. Unknown must not be represented by an invented zero. + FICostKind = "fi.cost.kind" + // FIAgentFidelity: Evidence fidelity: native-request, reconstructed-message, aggregate-turn or unknown. Only source-observed requests/messages may be LLM spans. + FIAgentFidelity = "fi.agent.fidelity" + // FIAgentTiming: Timing provenance: source, reconstructed or observed-event. Reconstructed message timing is not measured request latency or TTFT. + FIAgentTiming = "fi.agent.timing" + // FIAgentOutcome: Terminal outcome: success, error, interrupted or incomplete; missing stop events are incomplete, not success. + FIAgentOutcome = "fi.agent.outcome" + // FIAgentUsageAdditive: Boolean provenance flag for canonical usage ownership; not itself a backend aggregation gate. Request/attempt plans count each observed model operation once. For turn-only totals, place canonical usage exactly once on the last source-observed generation (marked scope=turn), or the AGENT root if there is no generation. Keep all other spans summary-only; never fabricate a model request. + FIAgentUsageAdditive = "fi.agent.usage.additive" + // FIAgentUsagePlan: One immutable plan per turn: request, attempt, turn or unknown. Never mix per-request counters and overlapping turn totals; unknown plans remain summary-only. + FIAgentUsagePlan = "fi.agent.usage.plan" + // FIAgentUsageCacheInInput: Boolean: source input count already includes cache reads/writes. Normalize input once; cache detail counters are subsets, not additional total tokens. + FIAgentUsageCacheInInput = "fi.agent.usage.cache_in_input" + // FIAgentUsageReasoningInOutput: Boolean: source output count already includes reasoning. Normalize output once; reasoning is a subset, not extra total tokens. + FIAgentUsageReasoningInOutput = "fi.agent.usage.reasoning_in_output" + // FIAgentCostSource: Source of the cost, for example reported or host-price-table; independent of whether this span contributes to totals. + FIAgentCostSource = "fi.agent.cost.source" + // FIAgentCostEstimator: Identifier/version of the estimator or price table for estimated costs; omit for reported costs. Never include credentials. + FIAgentCostEstimator = "fi.agent.cost.estimator" + // FIAgentGap: Bounded diagnostic code for missing evidence, for example MISSING_PARENT, MISSING_CHILD_STOP or UNRESOLVED_USAGE; not raw error content. + FIAgentGap = "fi.agent.gap" + // FIAgentTransport: Versioned transport contract identifier; not an endpoint URL or credential. + FIAgentTransport = "fi.agent.transport" + // FIAgentSourceCallID: Opaque integration correlation identifier; not a substitute for a source-provided tool_call.id. + FIAgentSourceCallID = "fi.agent.source_call_id" + // FIAgentSummaryInput: Non-additive normalized input token summary; never summed into canonical usage. + FIAgentSummaryInput = "fi.agent.summary.input" + // FIAgentSummaryOutput: Non-additive normalized output token summary; never summed into canonical usage. + FIAgentSummaryOutput = "fi.agent.summary.output" + // FIAgentSummaryTotal: Non-additive input plus output token summary; never summed into canonical usage. + FIAgentSummaryTotal = "fi.agent.summary.total" + // FIAgentSummaryCacheRead: Non-additive cache-read token summary, a subset of normalized input. + FIAgentSummaryCacheRead = "fi.agent.summary.cache_read" + // FIAgentSummaryCacheWrite: Non-additive cache-write token summary, a subset of normalized input. + FIAgentSummaryCacheWrite = "fi.agent.summary.cache_write" + // FIAgentSummaryReasoning: Non-additive reasoning token summary, a subset of normalized output. + FIAgentSummaryReasoning = "fi.agent.summary.reasoning" + // FIAgentSummaryCostUSD: Non-additive cost summary in USD; never place this amount in canonical cost as well unless this span owns the usage. + FIAgentSummaryCostUSD = "fi.agent.summary.cost_usd" + // FIAgentTags: JSON-encoded array of configured bounded tags, subject to the integration privacy policy. + FIAgentTags = "fi.agent.tags" + // FIAgentEvent: Agent lifecycle event type, for example compaction; not a model invocation. + FIAgentEvent = "fi.agent.event" + // FIAgentInputCompleteness: Source input completeness, for example partial; do not present an excerpt as the full model input. + FIAgentInputCompleteness = "fi.agent.input.completeness" + // FIAgentContentSource: Provenance of captured content, for example a source transcript; not evidence of native request capture. + FIAgentContentSource = "fi.agent.content.source" +) diff --git a/go/openai/agent_semantic_conventions_test.go b/go/openai/agent_semantic_conventions_test.go new file mode 100644 index 000000000..087d7fe77 --- /dev/null +++ b/go/openai/agent_semantic_conventions_test.go @@ -0,0 +1,44 @@ +package traceaiopenai + +import "testing" + +func TestCodingAgentWireContract(t *testing.T) { + for name, pair := range map[string][2]string{ + "GenAICostTotal": {GenAICostTotal, "gen_ai.cost.total"}, + "GenAICostInput": {GenAICostInput, "gen_ai.cost.input"}, + "GenAICostOutput": {GenAICostOutput, "gen_ai.cost.output"}, + "GenAIServerTimeToFirstToken": {GenAIServerTimeToFirstToken, "gen_ai.server.time_to_first_token"}, + "ToolName": {ToolName, "tool.name"}, + "ToolCallID": {ToolCallID, "tool_call.id"}, + "FIUsageScope": {FIUsageScope, "fi.usage.scope"}, + "FIUsageContribution": {FIUsageContribution, "fi.usage.contribution"}, + "FICostKind": {FICostKind, "fi.cost.kind"}, + "FIAgentFidelity": {FIAgentFidelity, "fi.agent.fidelity"}, + "FIAgentTiming": {FIAgentTiming, "fi.agent.timing"}, + "FIAgentOutcome": {FIAgentOutcome, "fi.agent.outcome"}, + "FIAgentUsageAdditive": {FIAgentUsageAdditive, "fi.agent.usage.additive"}, + "FIAgentUsagePlan": {FIAgentUsagePlan, "fi.agent.usage.plan"}, + "FIAgentUsageCacheInInput": {FIAgentUsageCacheInInput, "fi.agent.usage.cache_in_input"}, + "FIAgentUsageReasoningInOutput": {FIAgentUsageReasoningInOutput, "fi.agent.usage.reasoning_in_output"}, + "FIAgentCostSource": {FIAgentCostSource, "fi.agent.cost.source"}, + "FIAgentCostEstimator": {FIAgentCostEstimator, "fi.agent.cost.estimator"}, + "FIAgentGap": {FIAgentGap, "fi.agent.gap"}, + "FIAgentTransport": {FIAgentTransport, "fi.agent.transport"}, + "FIAgentSourceCallID": {FIAgentSourceCallID, "fi.agent.source_call_id"}, + "FIAgentSummaryInput": {FIAgentSummaryInput, "fi.agent.summary.input"}, + "FIAgentSummaryOutput": {FIAgentSummaryOutput, "fi.agent.summary.output"}, + "FIAgentSummaryTotal": {FIAgentSummaryTotal, "fi.agent.summary.total"}, + "FIAgentSummaryCacheRead": {FIAgentSummaryCacheRead, "fi.agent.summary.cache_read"}, + "FIAgentSummaryCacheWrite": {FIAgentSummaryCacheWrite, "fi.agent.summary.cache_write"}, + "FIAgentSummaryReasoning": {FIAgentSummaryReasoning, "fi.agent.summary.reasoning"}, + "FIAgentSummaryCostUSD": {FIAgentSummaryCostUSD, "fi.agent.summary.cost_usd"}, + "FIAgentTags": {FIAgentTags, "fi.agent.tags"}, + "FIAgentEvent": {FIAgentEvent, "fi.agent.event"}, + "FIAgentInputCompleteness": {FIAgentInputCompleteness, "fi.agent.input.completeness"}, + "FIAgentContentSource": {FIAgentContentSource, "fi.agent.content.source"}, + } { + if pair[0] != pair[1] { + t.Errorf("%s = %q, want %q", name, pair[0], pair[1]) + } + } +} diff --git a/go/openai/attributes.go b/go/openai/attributes.go index d2359decd..dc131b687 100644 --- a/go/openai/attributes.go +++ b/go/openai/attributes.go @@ -80,3 +80,69 @@ const ( SpanKindAgent = "AGENT" SpanKindChain = "CHAIN" ) + +// Coding-agent usage and provenance. fi.agent.* is metadata, not an aggregation gate. +const ( + // GenAICostTotal: Total cost in USD for this additive usage owner only; omit unknown costs, preserve an explicitly reported zero. + GenAICostTotal = "gen_ai.cost.total" + // GenAICostInput: Input cost in USD for this additive usage owner only; total cost takes precedence over input plus output. + GenAICostInput = "gen_ai.cost.input" + // GenAICostOutput: Output cost in USD for this additive usage owner only; total cost takes precedence over input plus output. + GenAICostOutput = "gen_ai.cost.output" + // GenAIServerTimeToFirstToken: Measured time to first token in milliseconds for the Future AGI span attribute consumer. Not the OTel histogram unit (seconds). Convert seconds to milliseconds before emission; omit for reconstructed timing. The current gateway seconds writer is inconsistent with the dashboard and requires a separate migration. + GenAIServerTimeToFirstToken = "gen_ai.server.time_to_first_token" + // ToolName: Source tool name on TOOL spans; do not rely on the display span name. + ToolName = "tool.name" + // FIUsageScope: Scope of canonical usage: request, attempt, turn or unknown. A turn aggregate is not a measured individual request. + FIUsageScope = "fi.usage.scope" + // FIUsageContribution: Use none for non-additive summaries and additive for the sole owner of canonical usage. Never duplicate canonical tokens or cost on summaries: older aggregate readers sum all span kinds. + FIUsageContribution = "fi.usage.contribution" + // FICostKind: Cost provenance understood by Future AGI: provider_reported, estimated or unknown. Unknown must not be represented by an invented zero. + FICostKind = "fi.cost.kind" + // FIAgentFidelity: Evidence fidelity: native-request, reconstructed-message, aggregate-turn or unknown. Only source-observed requests/messages may be LLM spans. + FIAgentFidelity = "fi.agent.fidelity" + // FIAgentTiming: Timing provenance: source, reconstructed or observed-event. Reconstructed message timing is not measured request latency or TTFT. + FIAgentTiming = "fi.agent.timing" + // FIAgentOutcome: Terminal outcome: success, error, interrupted or incomplete; missing stop events are incomplete, not success. + FIAgentOutcome = "fi.agent.outcome" + // FIAgentUsageAdditive: Boolean provenance flag for canonical usage ownership; not itself a backend aggregation gate. Request/attempt plans count each observed model operation once. For turn-only totals, place canonical usage exactly once on the last source-observed generation (marked scope=turn), or the AGENT root if there is no generation. Keep all other spans summary-only; never fabricate a model request. + FIAgentUsageAdditive = "fi.agent.usage.additive" + // FIAgentUsagePlan: One immutable plan per turn: request, attempt, turn or unknown. Never mix per-request counters and overlapping turn totals; unknown plans remain summary-only. + FIAgentUsagePlan = "fi.agent.usage.plan" + // FIAgentUsageCacheInInput: Boolean: source input count already includes cache reads/writes. Normalize input once; cache detail counters are subsets, not additional total tokens. + FIAgentUsageCacheInInput = "fi.agent.usage.cache_in_input" + // FIAgentUsageReasoningInOutput: Boolean: source output count already includes reasoning. Normalize output once; reasoning is a subset, not extra total tokens. + FIAgentUsageReasoningInOutput = "fi.agent.usage.reasoning_in_output" + // FIAgentCostSource: Source of the cost, for example reported or host-price-table; independent of whether this span contributes to totals. + FIAgentCostSource = "fi.agent.cost.source" + // FIAgentCostEstimator: Identifier/version of the estimator or price table for estimated costs; omit for reported costs. Never include credentials. + FIAgentCostEstimator = "fi.agent.cost.estimator" + // FIAgentGap: Bounded diagnostic code for missing evidence, for example MISSING_PARENT, MISSING_CHILD_STOP or UNRESOLVED_USAGE; not raw error content. + FIAgentGap = "fi.agent.gap" + // FIAgentTransport: Versioned transport contract identifier; not an endpoint URL or credential. + FIAgentTransport = "fi.agent.transport" + // FIAgentSourceCallID: Opaque integration correlation identifier; not a substitute for a source-provided tool_call.id. + FIAgentSourceCallID = "fi.agent.source_call_id" + // FIAgentSummaryInput: Non-additive normalized input token summary; never summed into canonical usage. + FIAgentSummaryInput = "fi.agent.summary.input" + // FIAgentSummaryOutput: Non-additive normalized output token summary; never summed into canonical usage. + FIAgentSummaryOutput = "fi.agent.summary.output" + // FIAgentSummaryTotal: Non-additive input plus output token summary; never summed into canonical usage. + FIAgentSummaryTotal = "fi.agent.summary.total" + // FIAgentSummaryCacheRead: Non-additive cache-read token summary, a subset of normalized input. + FIAgentSummaryCacheRead = "fi.agent.summary.cache_read" + // FIAgentSummaryCacheWrite: Non-additive cache-write token summary, a subset of normalized input. + FIAgentSummaryCacheWrite = "fi.agent.summary.cache_write" + // FIAgentSummaryReasoning: Non-additive reasoning token summary, a subset of normalized output. + FIAgentSummaryReasoning = "fi.agent.summary.reasoning" + // FIAgentSummaryCostUSD: Non-additive cost summary in USD; never place this amount in canonical cost as well unless this span owns the usage. + FIAgentSummaryCostUSD = "fi.agent.summary.cost_usd" + // FIAgentTags: JSON-encoded array of configured bounded tags, subject to the integration privacy policy. + FIAgentTags = "fi.agent.tags" + // FIAgentEvent: Agent lifecycle event type, for example compaction; not a model invocation. + FIAgentEvent = "fi.agent.event" + // FIAgentInputCompleteness: Source input completeness, for example partial; do not present an excerpt as the full model input. + FIAgentInputCompleteness = "fi.agent.input.completeness" + // FIAgentContentSource: Provenance of captured content, for example a source transcript; not evidence of native request capture. + FIAgentContentSource = "fi.agent.content.source" +) diff --git a/java/traceai-java-core/src/main/java/ai/traceai/SemanticConventions.java b/java/traceai-java-core/src/main/java/ai/traceai/SemanticConventions.java index 684af3808..d7796e6c8 100644 --- a/java/traceai-java-core/src/main/java/ai/traceai/SemanticConventions.java +++ b/java/traceai-java-core/src/main/java/ai/traceai/SemanticConventions.java @@ -8,6 +8,87 @@ */ public final class SemanticConventions { + // Coding-agent usage and provenance. + /** Scope of canonical usage: request, attempt, turn or unknown. A turn aggregate is not a measured individual request. */ + public static final String FI_USAGE_SCOPE = "fi.usage.scope"; + + /** Use none for non-additive summaries and additive for the sole owner of canonical usage. Never duplicate canonical tokens or cost on summaries: older aggregate readers sum all span kinds. */ + public static final String FI_USAGE_CONTRIBUTION = "fi.usage.contribution"; + + /** Cost provenance understood by Future AGI: provider_reported, estimated or unknown. Unknown must not be represented by an invented zero. */ + public static final String FI_COST_KIND = "fi.cost.kind"; + + /** Evidence fidelity: native-request, reconstructed-message, aggregate-turn or unknown. Only source-observed requests/messages may be LLM spans. */ + public static final String FI_AGENT_FIDELITY = "fi.agent.fidelity"; + + /** Timing provenance: source, reconstructed or observed-event. Reconstructed message timing is not measured request latency or TTFT. */ + public static final String FI_AGENT_TIMING = "fi.agent.timing"; + + /** Terminal outcome: success, error, interrupted or incomplete; missing stop events are incomplete, not success. */ + public static final String FI_AGENT_OUTCOME = "fi.agent.outcome"; + + /** Boolean provenance flag for canonical usage ownership; not itself a backend aggregation gate. Request/attempt plans count each observed model operation once. For turn-only totals, place canonical usage exactly once on the last source-observed generation (marked scope=turn), or the AGENT root if there is no generation. Keep all other spans summary-only; never fabricate a model request. */ + public static final String FI_AGENT_USAGE_ADDITIVE = "fi.agent.usage.additive"; + + /** One immutable plan per turn: request, attempt, turn or unknown. Never mix per-request counters and overlapping turn totals; unknown plans remain summary-only. */ + public static final String FI_AGENT_USAGE_PLAN = "fi.agent.usage.plan"; + + /** Boolean: source input count already includes cache reads/writes. Normalize input once; cache detail counters are subsets, not additional total tokens. */ + public static final String FI_AGENT_USAGE_CACHE_IN_INPUT = "fi.agent.usage.cache_in_input"; + + /** Boolean: source output count already includes reasoning. Normalize output once; reasoning is a subset, not extra total tokens. */ + public static final String FI_AGENT_USAGE_REASONING_IN_OUTPUT = "fi.agent.usage.reasoning_in_output"; + + /** Source of the cost, for example reported or host-price-table; independent of whether this span contributes to totals. */ + public static final String FI_AGENT_COST_SOURCE = "fi.agent.cost.source"; + + /** Identifier/version of the estimator or price table for estimated costs; omit for reported costs. Never include credentials. */ + public static final String FI_AGENT_COST_ESTIMATOR = "fi.agent.cost.estimator"; + + /** Bounded diagnostic code for missing evidence, for example MISSING_PARENT, MISSING_CHILD_STOP or UNRESOLVED_USAGE; not raw error content. */ + public static final String FI_AGENT_GAP = "fi.agent.gap"; + + /** Versioned transport contract identifier; not an endpoint URL or credential. */ + public static final String FI_AGENT_TRANSPORT = "fi.agent.transport"; + + /** Opaque integration correlation identifier; not a substitute for a source-provided tool_call.id. */ + public static final String FI_AGENT_SOURCE_CALL_ID = "fi.agent.source_call_id"; + + /** Non-additive normalized input token summary; never summed into canonical usage. */ + public static final String FI_AGENT_SUMMARY_INPUT = "fi.agent.summary.input"; + + /** Non-additive normalized output token summary; never summed into canonical usage. */ + public static final String FI_AGENT_SUMMARY_OUTPUT = "fi.agent.summary.output"; + + /** Non-additive input plus output token summary; never summed into canonical usage. */ + public static final String FI_AGENT_SUMMARY_TOTAL = "fi.agent.summary.total"; + + /** Non-additive cache-read token summary, a subset of normalized input. */ + public static final String FI_AGENT_SUMMARY_CACHE_READ = "fi.agent.summary.cache_read"; + + /** Non-additive cache-write token summary, a subset of normalized input. */ + public static final String FI_AGENT_SUMMARY_CACHE_WRITE = "fi.agent.summary.cache_write"; + + /** Non-additive reasoning token summary, a subset of normalized output. */ + public static final String FI_AGENT_SUMMARY_REASONING = "fi.agent.summary.reasoning"; + + /** Non-additive cost summary in USD; never place this amount in canonical cost as well unless this span owns the usage. */ + public static final String FI_AGENT_SUMMARY_COST_USD = "fi.agent.summary.cost_usd"; + + /** JSON-encoded array of configured bounded tags, subject to the integration privacy policy. */ + public static final String FI_AGENT_TAGS = "fi.agent.tags"; + + /** Agent lifecycle event type, for example compaction; not a model invocation. */ + public static final String FI_AGENT_EVENT = "fi.agent.event"; + + /** Source input completeness, for example partial; do not present an excerpt as the full model input. */ + public static final String FI_AGENT_INPUT_COMPLETENESS = "fi.agent.input.completeness"; + + /** Provenance of captured content, for example a source transcript; not evidence of native request capture. */ + public static final String FI_AGENT_CONTENT_SOURCE = "fi.agent.content.source"; + + + // ── FI Span Kind ───────────────────────────────────────────────── public static final String FI_SPAN_KIND = "fi.span.kind"; public static final String GEN_AI_SPAN_KIND = "gen_ai.span.kind"; @@ -133,6 +214,7 @@ public final class SemanticConventions { // ── GenAI Performance / Streaming ──────────────────────────────── public static final String GEN_AI_CLIENT_OPERATION_DURATION = "gen_ai.client.operation.duration"; + /** Measured time to first token in milliseconds for the Future AGI span attribute consumer. Not the OTel histogram unit (seconds). Convert seconds to milliseconds before emission; omit for reconstructed timing. The current gateway seconds writer is inconsistent with the dashboard and requires a separate migration. */ public static final String GEN_AI_SERVER_TIME_TO_FIRST_TOKEN = "gen_ai.server.time_to_first_token"; public static final String GEN_AI_SERVER_TIME_PER_OUTPUT_TOKEN = "gen_ai.server.time_per_output_token"; public static final String GEN_AI_SERVER_QUEUE_TIME = "gen_ai.server.queue_time"; diff --git a/java/traceai-java-core/src/test/java/ai/traceai/AgentSemanticConventionsTest.java b/java/traceai-java-core/src/test/java/ai/traceai/AgentSemanticConventionsTest.java new file mode 100644 index 000000000..7e8f709c9 --- /dev/null +++ b/java/traceai-java-core/src/test/java/ai/traceai/AgentSemanticConventionsTest.java @@ -0,0 +1,42 @@ +package ai.traceai; + +import org.junit.jupiter.api.Test; +import static org.junit.jupiter.api.Assertions.assertEquals; + +class AgentSemanticConventionsTest { + @Test + void codingAgentWireContract() { + assertEquals("gen_ai.cost.total", SemanticConventions.GEN_AI_COST_TOTAL); + assertEquals("gen_ai.cost.input", SemanticConventions.GEN_AI_COST_INPUT); + assertEquals("gen_ai.cost.output", SemanticConventions.GEN_AI_COST_OUTPUT); + assertEquals("gen_ai.server.time_to_first_token", SemanticConventions.GEN_AI_SERVER_TIME_TO_FIRST_TOKEN); + assertEquals("tool.name", SemanticConventions.TOOL_NAME); + assertEquals("tool_call.id", SemanticConventions.TOOL_CALL_ID); + assertEquals("fi.usage.scope", SemanticConventions.FI_USAGE_SCOPE); + assertEquals("fi.usage.contribution", SemanticConventions.FI_USAGE_CONTRIBUTION); + assertEquals("fi.cost.kind", SemanticConventions.FI_COST_KIND); + assertEquals("fi.agent.fidelity", SemanticConventions.FI_AGENT_FIDELITY); + assertEquals("fi.agent.timing", SemanticConventions.FI_AGENT_TIMING); + assertEquals("fi.agent.outcome", SemanticConventions.FI_AGENT_OUTCOME); + assertEquals("fi.agent.usage.additive", SemanticConventions.FI_AGENT_USAGE_ADDITIVE); + assertEquals("fi.agent.usage.plan", SemanticConventions.FI_AGENT_USAGE_PLAN); + assertEquals("fi.agent.usage.cache_in_input", SemanticConventions.FI_AGENT_USAGE_CACHE_IN_INPUT); + assertEquals("fi.agent.usage.reasoning_in_output", SemanticConventions.FI_AGENT_USAGE_REASONING_IN_OUTPUT); + assertEquals("fi.agent.cost.source", SemanticConventions.FI_AGENT_COST_SOURCE); + assertEquals("fi.agent.cost.estimator", SemanticConventions.FI_AGENT_COST_ESTIMATOR); + assertEquals("fi.agent.gap", SemanticConventions.FI_AGENT_GAP); + assertEquals("fi.agent.transport", SemanticConventions.FI_AGENT_TRANSPORT); + assertEquals("fi.agent.source_call_id", SemanticConventions.FI_AGENT_SOURCE_CALL_ID); + assertEquals("fi.agent.summary.input", SemanticConventions.FI_AGENT_SUMMARY_INPUT); + assertEquals("fi.agent.summary.output", SemanticConventions.FI_AGENT_SUMMARY_OUTPUT); + assertEquals("fi.agent.summary.total", SemanticConventions.FI_AGENT_SUMMARY_TOTAL); + assertEquals("fi.agent.summary.cache_read", SemanticConventions.FI_AGENT_SUMMARY_CACHE_READ); + assertEquals("fi.agent.summary.cache_write", SemanticConventions.FI_AGENT_SUMMARY_CACHE_WRITE); + assertEquals("fi.agent.summary.reasoning", SemanticConventions.FI_AGENT_SUMMARY_REASONING); + assertEquals("fi.agent.summary.cost_usd", SemanticConventions.FI_AGENT_SUMMARY_COST_USD); + assertEquals("fi.agent.tags", SemanticConventions.FI_AGENT_TAGS); + assertEquals("fi.agent.event", SemanticConventions.FI_AGENT_EVENT); + assertEquals("fi.agent.input.completeness", SemanticConventions.FI_AGENT_INPUT_COMPLETENESS); + assertEquals("fi.agent.content.source", SemanticConventions.FI_AGENT_CONTENT_SOURCE); + } +} diff --git a/python/fi_instrumentation/fi_types.py b/python/fi_instrumentation/fi_types.py index 070ba41b8..6974f4c6e 100644 --- a/python/fi_instrumentation/fi_types.py +++ b/python/fi_instrumentation/fi_types.py @@ -22,6 +22,91 @@ class SpanAttributes: # OTEL GenAI Core Attributes (gen_ai.*) # ============================================================================= + # Coding-agent usage and provenance (fi.agent.* is metadata, not an aggregation gate). + TOOL_CALL_ID = "tool_call.id" + """Source tool-call identifier when available; omit rather than invent an identifier.""" + + TOOL_NAME = "tool.name" + """Source tool name on TOOL spans; do not rely on the display span name.""" + + FI_USAGE_SCOPE = "fi.usage.scope" + """Scope of canonical usage: request, attempt, turn or unknown. A turn aggregate is not a measured individual request.""" + + FI_USAGE_CONTRIBUTION = "fi.usage.contribution" + """Use none for non-additive summaries and additive for the sole owner of canonical usage. Never duplicate canonical tokens or cost on summaries: older aggregate readers sum all span kinds.""" + + FI_COST_KIND = "fi.cost.kind" + """Cost provenance understood by Future AGI: provider_reported, estimated or unknown. Unknown must not be represented by an invented zero.""" + + FI_AGENT_FIDELITY = "fi.agent.fidelity" + """Evidence fidelity: native-request, reconstructed-message, aggregate-turn or unknown. Only source-observed requests/messages may be LLM spans.""" + + FI_AGENT_TIMING = "fi.agent.timing" + """Timing provenance: source, reconstructed or observed-event. Reconstructed message timing is not measured request latency or TTFT.""" + + FI_AGENT_OUTCOME = "fi.agent.outcome" + """Terminal outcome: success, error, interrupted or incomplete; missing stop events are incomplete, not success.""" + + FI_AGENT_USAGE_ADDITIVE = "fi.agent.usage.additive" + """Boolean provenance flag for canonical usage ownership; not itself a backend aggregation gate. Request/attempt plans count each observed model operation once. For turn-only totals, place canonical usage exactly once on the last source-observed generation (marked scope=turn), or the AGENT root if there is no generation. Keep all other spans summary-only; never fabricate a model request.""" + + FI_AGENT_USAGE_PLAN = "fi.agent.usage.plan" + """One immutable plan per turn: request, attempt, turn or unknown. Never mix per-request counters and overlapping turn totals; unknown plans remain summary-only.""" + + FI_AGENT_USAGE_CACHE_IN_INPUT = "fi.agent.usage.cache_in_input" + """Boolean: source input count already includes cache reads/writes. Normalize input once; cache detail counters are subsets, not additional total tokens.""" + + FI_AGENT_USAGE_REASONING_IN_OUTPUT = "fi.agent.usage.reasoning_in_output" + """Boolean: source output count already includes reasoning. Normalize output once; reasoning is a subset, not extra total tokens.""" + + FI_AGENT_COST_SOURCE = "fi.agent.cost.source" + """Source of the cost, for example reported or host-price-table; independent of whether this span contributes to totals.""" + + FI_AGENT_COST_ESTIMATOR = "fi.agent.cost.estimator" + """Identifier/version of the estimator or price table for estimated costs; omit for reported costs. Never include credentials.""" + + FI_AGENT_GAP = "fi.agent.gap" + """Bounded diagnostic code for missing evidence, for example MISSING_PARENT, MISSING_CHILD_STOP or UNRESOLVED_USAGE; not raw error content.""" + + FI_AGENT_TRANSPORT = "fi.agent.transport" + """Versioned transport contract identifier; not an endpoint URL or credential.""" + + FI_AGENT_SOURCE_CALL_ID = "fi.agent.source_call_id" + """Opaque integration correlation identifier; not a substitute for a source-provided tool_call.id.""" + + FI_AGENT_SUMMARY_INPUT = "fi.agent.summary.input" + """Non-additive normalized input token summary; never summed into canonical usage.""" + + FI_AGENT_SUMMARY_OUTPUT = "fi.agent.summary.output" + """Non-additive normalized output token summary; never summed into canonical usage.""" + + FI_AGENT_SUMMARY_TOTAL = "fi.agent.summary.total" + """Non-additive input plus output token summary; never summed into canonical usage.""" + + FI_AGENT_SUMMARY_CACHE_READ = "fi.agent.summary.cache_read" + """Non-additive cache-read token summary, a subset of normalized input.""" + + FI_AGENT_SUMMARY_CACHE_WRITE = "fi.agent.summary.cache_write" + """Non-additive cache-write token summary, a subset of normalized input.""" + + FI_AGENT_SUMMARY_REASONING = "fi.agent.summary.reasoning" + """Non-additive reasoning token summary, a subset of normalized output.""" + + FI_AGENT_SUMMARY_COST_USD = "fi.agent.summary.cost_usd" + """Non-additive cost summary in USD; never place this amount in canonical cost as well unless this span owns the usage.""" + + FI_AGENT_TAGS = "fi.agent.tags" + """JSON-encoded array of configured bounded tags, subject to the integration privacy policy.""" + + FI_AGENT_EVENT = "fi.agent.event" + """Agent lifecycle event type, for example compaction; not a model invocation.""" + + FI_AGENT_INPUT_COMPLETENESS = "fi.agent.input.completeness" + """Source input completeness, for example partial; do not present an excerpt as the full model input.""" + + FI_AGENT_CONTENT_SOURCE = "fi.agent.content.source" + """Provenance of captured content, for example a source transcript; not evidence of native request capture.""" + # --- Operation & Provider --- GEN_AI_OPERATION_NAME = "gen_ai.operation.name" """The name of the operation being performed (chat, embeddings, text_completion, etc.)""" @@ -509,7 +594,7 @@ class SpanAttributes: # --- Performance & Streaming --- GEN_AI_SERVER_TIME_TO_FIRST_TOKEN = "gen_ai.server.time_to_first_token" - """Time to first token in milliseconds.""" + """Measured time to first token in milliseconds for the Future AGI span attribute consumer. Not the OTel histogram unit (seconds). Convert seconds to milliseconds before emission; omit for reconstructed timing. The current gateway seconds writer is inconsistent with the dashboard and requires a separate migration.""" GEN_AI_SERVER_TIME_PER_OUTPUT_TOKEN = "gen_ai.server.time_per_output_token" """Average time per output token in milliseconds.""" diff --git a/python/tests/test_agent_semantic_conventions.py b/python/tests/test_agent_semantic_conventions.py new file mode 100644 index 000000000..1bb01d1eb --- /dev/null +++ b/python/tests/test_agent_semantic_conventions.py @@ -0,0 +1,41 @@ +"""Pin coding-agent semantic convention wire values.""" +import pytest +from fi_instrumentation.fi_types import SpanAttributes + + +@pytest.mark.parametrize("name, expected", [ + ("GEN_AI_COST_TOTAL", "gen_ai.cost.total"), + ("GEN_AI_COST_INPUT", "gen_ai.cost.input"), + ("GEN_AI_COST_OUTPUT", "gen_ai.cost.output"), + ("GEN_AI_SERVER_TIME_TO_FIRST_TOKEN", "gen_ai.server.time_to_first_token"), + ("TOOL_NAME", "tool.name"), + ("TOOL_CALL_ID", "tool_call.id"), + ("FI_USAGE_SCOPE", "fi.usage.scope"), + ("FI_USAGE_CONTRIBUTION", "fi.usage.contribution"), + ("FI_COST_KIND", "fi.cost.kind"), + ("FI_AGENT_FIDELITY", "fi.agent.fidelity"), + ("FI_AGENT_TIMING", "fi.agent.timing"), + ("FI_AGENT_OUTCOME", "fi.agent.outcome"), + ("FI_AGENT_USAGE_ADDITIVE", "fi.agent.usage.additive"), + ("FI_AGENT_USAGE_PLAN", "fi.agent.usage.plan"), + ("FI_AGENT_USAGE_CACHE_IN_INPUT", "fi.agent.usage.cache_in_input"), + ("FI_AGENT_USAGE_REASONING_IN_OUTPUT", "fi.agent.usage.reasoning_in_output"), + ("FI_AGENT_COST_SOURCE", "fi.agent.cost.source"), + ("FI_AGENT_COST_ESTIMATOR", "fi.agent.cost.estimator"), + ("FI_AGENT_GAP", "fi.agent.gap"), + ("FI_AGENT_TRANSPORT", "fi.agent.transport"), + ("FI_AGENT_SOURCE_CALL_ID", "fi.agent.source_call_id"), + ("FI_AGENT_SUMMARY_INPUT", "fi.agent.summary.input"), + ("FI_AGENT_SUMMARY_OUTPUT", "fi.agent.summary.output"), + ("FI_AGENT_SUMMARY_TOTAL", "fi.agent.summary.total"), + ("FI_AGENT_SUMMARY_CACHE_READ", "fi.agent.summary.cache_read"), + ("FI_AGENT_SUMMARY_CACHE_WRITE", "fi.agent.summary.cache_write"), + ("FI_AGENT_SUMMARY_REASONING", "fi.agent.summary.reasoning"), + ("FI_AGENT_SUMMARY_COST_USD", "fi.agent.summary.cost_usd"), + ("FI_AGENT_TAGS", "fi.agent.tags"), + ("FI_AGENT_EVENT", "fi.agent.event"), + ("FI_AGENT_INPUT_COMPLETENESS", "fi.agent.input.completeness"), + ("FI_AGENT_CONTENT_SOURCE", "fi.agent.content.source"), +]) +def test_agent_wire_contract(name, expected): + assert getattr(SpanAttributes, name) == expected diff --git a/typescript/packages/fi-semantic-conventions/src/__tests__/agent-conventions.test.ts b/typescript/packages/fi-semantic-conventions/src/__tests__/agent-conventions.test.ts new file mode 100644 index 000000000..c226e8842 --- /dev/null +++ b/typescript/packages/fi-semantic-conventions/src/__tests__/agent-conventions.test.ts @@ -0,0 +1,133 @@ +import * as exported from "../index"; +import { SemanticConventions as SC } from "../index"; + +describe("coding-agent wire contract", () => { + test("GEN_AI_COST_TOTAL", () => { + expect(exported.GEN_AI_COST_TOTAL).toBe("gen_ai.cost.total"); + expect(SC.GEN_AI_COST_TOTAL).toBe("gen_ai.cost.total"); + }); + test("GEN_AI_COST_INPUT", () => { + expect(exported.GEN_AI_COST_INPUT).toBe("gen_ai.cost.input"); + expect(SC.GEN_AI_COST_INPUT).toBe("gen_ai.cost.input"); + }); + test("GEN_AI_COST_OUTPUT", () => { + expect(exported.GEN_AI_COST_OUTPUT).toBe("gen_ai.cost.output"); + expect(SC.GEN_AI_COST_OUTPUT).toBe("gen_ai.cost.output"); + }); + test("GEN_AI_SERVER_TIME_TO_FIRST_TOKEN", () => { + expect(exported.GEN_AI_SERVER_TIME_TO_FIRST_TOKEN).toBe("gen_ai.server.time_to_first_token"); + expect(SC.GEN_AI_SERVER_TIME_TO_FIRST_TOKEN).toBe("gen_ai.server.time_to_first_token"); + }); + test("TOOL_NAME", () => { + expect(exported.TOOL_NAME).toBe("tool.name"); + expect(SC.TOOL_NAME).toBe("tool.name"); + }); + test("TOOL_CALL_ID", () => { + expect(exported.TOOL_CALL_ID).toBe("tool_call.id"); + expect(SC.TOOL_CALL_ID).toBe("tool_call.id"); + }); + test("FI_USAGE_SCOPE", () => { + expect(exported.FI_USAGE_SCOPE).toBe("fi.usage.scope"); + expect(SC.FI_USAGE_SCOPE).toBe("fi.usage.scope"); + }); + test("FI_USAGE_CONTRIBUTION", () => { + expect(exported.FI_USAGE_CONTRIBUTION).toBe("fi.usage.contribution"); + expect(SC.FI_USAGE_CONTRIBUTION).toBe("fi.usage.contribution"); + }); + test("FI_COST_KIND", () => { + expect(exported.FI_COST_KIND).toBe("fi.cost.kind"); + expect(SC.FI_COST_KIND).toBe("fi.cost.kind"); + }); + test("FI_AGENT_FIDELITY", () => { + expect(exported.FI_AGENT_FIDELITY).toBe("fi.agent.fidelity"); + expect(SC.FI_AGENT_FIDELITY).toBe("fi.agent.fidelity"); + }); + test("FI_AGENT_TIMING", () => { + expect(exported.FI_AGENT_TIMING).toBe("fi.agent.timing"); + expect(SC.FI_AGENT_TIMING).toBe("fi.agent.timing"); + }); + test("FI_AGENT_OUTCOME", () => { + expect(exported.FI_AGENT_OUTCOME).toBe("fi.agent.outcome"); + expect(SC.FI_AGENT_OUTCOME).toBe("fi.agent.outcome"); + }); + test("FI_AGENT_USAGE_ADDITIVE", () => { + expect(exported.FI_AGENT_USAGE_ADDITIVE).toBe("fi.agent.usage.additive"); + expect(SC.FI_AGENT_USAGE_ADDITIVE).toBe("fi.agent.usage.additive"); + }); + test("FI_AGENT_USAGE_PLAN", () => { + expect(exported.FI_AGENT_USAGE_PLAN).toBe("fi.agent.usage.plan"); + expect(SC.FI_AGENT_USAGE_PLAN).toBe("fi.agent.usage.plan"); + }); + test("FI_AGENT_USAGE_CACHE_IN_INPUT", () => { + expect(exported.FI_AGENT_USAGE_CACHE_IN_INPUT).toBe("fi.agent.usage.cache_in_input"); + expect(SC.FI_AGENT_USAGE_CACHE_IN_INPUT).toBe("fi.agent.usage.cache_in_input"); + }); + test("FI_AGENT_USAGE_REASONING_IN_OUTPUT", () => { + expect(exported.FI_AGENT_USAGE_REASONING_IN_OUTPUT).toBe("fi.agent.usage.reasoning_in_output"); + expect(SC.FI_AGENT_USAGE_REASONING_IN_OUTPUT).toBe("fi.agent.usage.reasoning_in_output"); + }); + test("FI_AGENT_COST_SOURCE", () => { + expect(exported.FI_AGENT_COST_SOURCE).toBe("fi.agent.cost.source"); + expect(SC.FI_AGENT_COST_SOURCE).toBe("fi.agent.cost.source"); + }); + test("FI_AGENT_COST_ESTIMATOR", () => { + expect(exported.FI_AGENT_COST_ESTIMATOR).toBe("fi.agent.cost.estimator"); + expect(SC.FI_AGENT_COST_ESTIMATOR).toBe("fi.agent.cost.estimator"); + }); + test("FI_AGENT_GAP", () => { + expect(exported.FI_AGENT_GAP).toBe("fi.agent.gap"); + expect(SC.FI_AGENT_GAP).toBe("fi.agent.gap"); + }); + test("FI_AGENT_TRANSPORT", () => { + expect(exported.FI_AGENT_TRANSPORT).toBe("fi.agent.transport"); + expect(SC.FI_AGENT_TRANSPORT).toBe("fi.agent.transport"); + }); + test("FI_AGENT_SOURCE_CALL_ID", () => { + expect(exported.FI_AGENT_SOURCE_CALL_ID).toBe("fi.agent.source_call_id"); + expect(SC.FI_AGENT_SOURCE_CALL_ID).toBe("fi.agent.source_call_id"); + }); + test("FI_AGENT_SUMMARY_INPUT", () => { + expect(exported.FI_AGENT_SUMMARY_INPUT).toBe("fi.agent.summary.input"); + expect(SC.FI_AGENT_SUMMARY_INPUT).toBe("fi.agent.summary.input"); + }); + test("FI_AGENT_SUMMARY_OUTPUT", () => { + expect(exported.FI_AGENT_SUMMARY_OUTPUT).toBe("fi.agent.summary.output"); + expect(SC.FI_AGENT_SUMMARY_OUTPUT).toBe("fi.agent.summary.output"); + }); + test("FI_AGENT_SUMMARY_TOTAL", () => { + expect(exported.FI_AGENT_SUMMARY_TOTAL).toBe("fi.agent.summary.total"); + expect(SC.FI_AGENT_SUMMARY_TOTAL).toBe("fi.agent.summary.total"); + }); + test("FI_AGENT_SUMMARY_CACHE_READ", () => { + expect(exported.FI_AGENT_SUMMARY_CACHE_READ).toBe("fi.agent.summary.cache_read"); + expect(SC.FI_AGENT_SUMMARY_CACHE_READ).toBe("fi.agent.summary.cache_read"); + }); + test("FI_AGENT_SUMMARY_CACHE_WRITE", () => { + expect(exported.FI_AGENT_SUMMARY_CACHE_WRITE).toBe("fi.agent.summary.cache_write"); + expect(SC.FI_AGENT_SUMMARY_CACHE_WRITE).toBe("fi.agent.summary.cache_write"); + }); + test("FI_AGENT_SUMMARY_REASONING", () => { + expect(exported.FI_AGENT_SUMMARY_REASONING).toBe("fi.agent.summary.reasoning"); + expect(SC.FI_AGENT_SUMMARY_REASONING).toBe("fi.agent.summary.reasoning"); + }); + test("FI_AGENT_SUMMARY_COST_USD", () => { + expect(exported.FI_AGENT_SUMMARY_COST_USD).toBe("fi.agent.summary.cost_usd"); + expect(SC.FI_AGENT_SUMMARY_COST_USD).toBe("fi.agent.summary.cost_usd"); + }); + test("FI_AGENT_TAGS", () => { + expect(exported.FI_AGENT_TAGS).toBe("fi.agent.tags"); + expect(SC.FI_AGENT_TAGS).toBe("fi.agent.tags"); + }); + test("FI_AGENT_EVENT", () => { + expect(exported.FI_AGENT_EVENT).toBe("fi.agent.event"); + expect(SC.FI_AGENT_EVENT).toBe("fi.agent.event"); + }); + test("FI_AGENT_INPUT_COMPLETENESS", () => { + expect(exported.FI_AGENT_INPUT_COMPLETENESS).toBe("fi.agent.input.completeness"); + expect(SC.FI_AGENT_INPUT_COMPLETENESS).toBe("fi.agent.input.completeness"); + }); + test("FI_AGENT_CONTENT_SOURCE", () => { + expect(exported.FI_AGENT_CONTENT_SOURCE).toBe("fi.agent.content.source"); + expect(SC.FI_AGENT_CONTENT_SOURCE).toBe("fi.agent.content.source"); + }); +}); diff --git a/typescript/packages/fi-semantic-conventions/src/trace/SemanticConventions.ts b/typescript/packages/fi-semantic-conventions/src/trace/SemanticConventions.ts index b2dd3150a..98b078ab3 100644 --- a/typescript/packages/fi-semantic-conventions/src/trace/SemanticConventions.ts +++ b/typescript/packages/fi-semantic-conventions/src/trace/SemanticConventions.ts @@ -504,7 +504,130 @@ export const SemanticAttributePrefixes = { */ export const GRAPH_NODE_PARENT_ID = "graph.node.parent_id" as const; + + // Coding-agent usage and provenance. fi.agent.* is metadata, not a backend aggregation gate. + /** Total cost in USD for this additive usage owner only; omit unknown costs, preserve an explicitly reported zero. */ + export const GEN_AI_COST_TOTAL = "gen_ai.cost.total" as const; + + /** Input cost in USD for this additive usage owner only; total cost takes precedence over input plus output. */ + export const GEN_AI_COST_INPUT = "gen_ai.cost.input" as const; + + /** Output cost in USD for this additive usage owner only; total cost takes precedence over input plus output. */ + export const GEN_AI_COST_OUTPUT = "gen_ai.cost.output" as const; + + /** Measured time to first token in milliseconds for the Future AGI span attribute consumer. Not the OTel histogram unit (seconds). Convert seconds to milliseconds before emission; omit for reconstructed timing. The current gateway seconds writer is inconsistent with the dashboard and requires a separate migration. */ + export const GEN_AI_SERVER_TIME_TO_FIRST_TOKEN = "gen_ai.server.time_to_first_token" as const; + + /** Scope of canonical usage: request, attempt, turn or unknown. A turn aggregate is not a measured individual request. */ + export const FI_USAGE_SCOPE = "fi.usage.scope" as const; + + /** Use none for non-additive summaries and additive for the sole owner of canonical usage. Never duplicate canonical tokens or cost on summaries: older aggregate readers sum all span kinds. */ + export const FI_USAGE_CONTRIBUTION = "fi.usage.contribution" as const; + + /** Cost provenance understood by Future AGI: provider_reported, estimated or unknown. Unknown must not be represented by an invented zero. */ + export const FI_COST_KIND = "fi.cost.kind" as const; + + /** Evidence fidelity: native-request, reconstructed-message, aggregate-turn or unknown. Only source-observed requests/messages may be LLM spans. */ + export const FI_AGENT_FIDELITY = "fi.agent.fidelity" as const; + + /** Timing provenance: source, reconstructed or observed-event. Reconstructed message timing is not measured request latency or TTFT. */ + export const FI_AGENT_TIMING = "fi.agent.timing" as const; + + /** Terminal outcome: success, error, interrupted or incomplete; missing stop events are incomplete, not success. */ + export const FI_AGENT_OUTCOME = "fi.agent.outcome" as const; + + /** Boolean provenance flag for canonical usage ownership; not itself a backend aggregation gate. Request/attempt plans count each observed model operation once. For turn-only totals, place canonical usage exactly once on the last source-observed generation (marked scope=turn), or the AGENT root if there is no generation. Keep all other spans summary-only; never fabricate a model request. */ + export const FI_AGENT_USAGE_ADDITIVE = "fi.agent.usage.additive" as const; + + /** One immutable plan per turn: request, attempt, turn or unknown. Never mix per-request counters and overlapping turn totals; unknown plans remain summary-only. */ + export const FI_AGENT_USAGE_PLAN = "fi.agent.usage.plan" as const; + + /** Boolean: source input count already includes cache reads/writes. Normalize input once; cache detail counters are subsets, not additional total tokens. */ + export const FI_AGENT_USAGE_CACHE_IN_INPUT = "fi.agent.usage.cache_in_input" as const; + + /** Boolean: source output count already includes reasoning. Normalize output once; reasoning is a subset, not extra total tokens. */ + export const FI_AGENT_USAGE_REASONING_IN_OUTPUT = "fi.agent.usage.reasoning_in_output" as const; + + /** Source of the cost, for example reported or host-price-table; independent of whether this span contributes to totals. */ + export const FI_AGENT_COST_SOURCE = "fi.agent.cost.source" as const; + + /** Identifier/version of the estimator or price table for estimated costs; omit for reported costs. Never include credentials. */ + export const FI_AGENT_COST_ESTIMATOR = "fi.agent.cost.estimator" as const; + + /** Bounded diagnostic code for missing evidence, for example MISSING_PARENT, MISSING_CHILD_STOP or UNRESOLVED_USAGE; not raw error content. */ + export const FI_AGENT_GAP = "fi.agent.gap" as const; + + /** Versioned transport contract identifier; not an endpoint URL or credential. */ + export const FI_AGENT_TRANSPORT = "fi.agent.transport" as const; + + /** Opaque integration correlation identifier; not a substitute for a source-provided tool_call.id. */ + export const FI_AGENT_SOURCE_CALL_ID = "fi.agent.source_call_id" as const; + + /** Non-additive normalized input token summary; never summed into canonical usage. */ + export const FI_AGENT_SUMMARY_INPUT = "fi.agent.summary.input" as const; + + /** Non-additive normalized output token summary; never summed into canonical usage. */ + export const FI_AGENT_SUMMARY_OUTPUT = "fi.agent.summary.output" as const; + + /** Non-additive input plus output token summary; never summed into canonical usage. */ + export const FI_AGENT_SUMMARY_TOTAL = "fi.agent.summary.total" as const; + + /** Non-additive cache-read token summary, a subset of normalized input. */ + export const FI_AGENT_SUMMARY_CACHE_READ = "fi.agent.summary.cache_read" as const; + + /** Non-additive cache-write token summary, a subset of normalized input. */ + export const FI_AGENT_SUMMARY_CACHE_WRITE = "fi.agent.summary.cache_write" as const; + + /** Non-additive reasoning token summary, a subset of normalized output. */ + export const FI_AGENT_SUMMARY_REASONING = "fi.agent.summary.reasoning" as const; + + /** Non-additive cost summary in USD; never place this amount in canonical cost as well unless this span owns the usage. */ + export const FI_AGENT_SUMMARY_COST_USD = "fi.agent.summary.cost_usd" as const; + + /** JSON-encoded array of configured bounded tags, subject to the integration privacy policy. */ + export const FI_AGENT_TAGS = "fi.agent.tags" as const; + + /** Agent lifecycle event type, for example compaction; not a model invocation. */ + export const FI_AGENT_EVENT = "fi.agent.event" as const; + + /** Source input completeness, for example partial; do not present an excerpt as the full model input. */ + export const FI_AGENT_INPUT_COMPLETENESS = "fi.agent.input.completeness" as const; + + /** Provenance of captured content, for example a source transcript; not evidence of native request capture. */ + export const FI_AGENT_CONTENT_SOURCE = "fi.agent.content.source" as const; + export const SemanticConventions = { + GEN_AI_COST_TOTAL, + GEN_AI_COST_INPUT, + GEN_AI_COST_OUTPUT, + GEN_AI_SERVER_TIME_TO_FIRST_TOKEN, + FI_USAGE_SCOPE, + FI_USAGE_CONTRIBUTION, + FI_COST_KIND, + FI_AGENT_FIDELITY, + FI_AGENT_TIMING, + FI_AGENT_OUTCOME, + FI_AGENT_USAGE_ADDITIVE, + FI_AGENT_USAGE_PLAN, + FI_AGENT_USAGE_CACHE_IN_INPUT, + FI_AGENT_USAGE_REASONING_IN_OUTPUT, + FI_AGENT_COST_SOURCE, + FI_AGENT_COST_ESTIMATOR, + FI_AGENT_GAP, + FI_AGENT_TRANSPORT, + FI_AGENT_SOURCE_CALL_ID, + FI_AGENT_SUMMARY_INPUT, + FI_AGENT_SUMMARY_OUTPUT, + FI_AGENT_SUMMARY_TOTAL, + FI_AGENT_SUMMARY_CACHE_READ, + FI_AGENT_SUMMARY_CACHE_WRITE, + FI_AGENT_SUMMARY_REASONING, + FI_AGENT_SUMMARY_COST_USD, + FI_AGENT_TAGS, + FI_AGENT_EVENT, + FI_AGENT_INPUT_COMPLETENESS, + FI_AGENT_CONTENT_SOURCE, + IMAGE_URL, INPUT_VALUE, INPUT_MIME_TYPE,