Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions csharp/src/FIInstrumentation/SemanticConventions.cs
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,89 @@ namespace FIInstrumentation;
/// </summary>
public static class SemanticConventions
{
// Coding-agent usage and provenance.
/// <summary>Source tool name on TOOL spans; do not rely on the display span name.</summary>
public const string ToolName = "tool.name";

/// <summary>Scope of canonical usage: request, attempt, turn or unknown. A turn aggregate is not a measured individual request.</summary>
public const string FiUsageScope = "fi.usage.scope";

/// <summary>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.</summary>
public const string FiUsageContribution = "fi.usage.contribution";

/// <summary>Cost provenance understood by Future AGI: provider_reported, estimated or unknown. Unknown must not be represented by an invented zero.</summary>
public const string FiCostKind = "fi.cost.kind";

/// <summary>Evidence fidelity: native-request, reconstructed-message, aggregate-turn or unknown. Only source-observed requests/messages may be LLM spans.</summary>
public const string FiAgentFidelity = "fi.agent.fidelity";

/// <summary>Timing provenance: source, reconstructed or observed-event. Reconstructed message timing is not measured request latency or TTFT.</summary>
public const string FiAgentTiming = "fi.agent.timing";

/// <summary>Terminal outcome: success, error, interrupted or incomplete; missing stop events are incomplete, not success.</summary>
public const string FiAgentOutcome = "fi.agent.outcome";

/// <summary>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.</summary>
public const string FiAgentUsageAdditive = "fi.agent.usage.additive";

/// <summary>One immutable plan per turn: request, attempt, turn or unknown. Never mix per-request counters and overlapping turn totals; unknown plans remain summary-only.</summary>
public const string FiAgentUsagePlan = "fi.agent.usage.plan";

/// <summary>Boolean: source input count already includes cache reads/writes. Normalize input once; cache detail counters are subsets, not additional total tokens.</summary>
public const string FiAgentUsageCacheInInput = "fi.agent.usage.cache_in_input";

/// <summary>Boolean: source output count already includes reasoning. Normalize output once; reasoning is a subset, not extra total tokens.</summary>
public const string FiAgentUsageReasoningInOutput = "fi.agent.usage.reasoning_in_output";

/// <summary>Source of the cost, for example reported or host-price-table; independent of whether this span contributes to totals.</summary>
public const string FiAgentCostSource = "fi.agent.cost.source";

/// <summary>Identifier/version of the estimator or price table for estimated costs; omit for reported costs. Never include credentials.</summary>
public const string FiAgentCostEstimator = "fi.agent.cost.estimator";

/// <summary>Bounded diagnostic code for missing evidence, for example MISSING_PARENT, MISSING_CHILD_STOP or UNRESOLVED_USAGE; not raw error content.</summary>
public const string FiAgentGap = "fi.agent.gap";

/// <summary>Versioned transport contract identifier; not an endpoint URL or credential.</summary>
public const string FiAgentTransport = "fi.agent.transport";

/// <summary>Opaque integration correlation identifier; not a substitute for a source-provided tool_call.id.</summary>
public const string FiAgentSourceCallId = "fi.agent.source_call_id";

/// <summary>Non-additive normalized input token summary; never summed into canonical usage.</summary>
public const string FiAgentSummaryInput = "fi.agent.summary.input";

/// <summary>Non-additive normalized output token summary; never summed into canonical usage.</summary>
public const string FiAgentSummaryOutput = "fi.agent.summary.output";

/// <summary>Non-additive input plus output token summary; never summed into canonical usage.</summary>
public const string FiAgentSummaryTotal = "fi.agent.summary.total";

/// <summary>Non-additive cache-read token summary, a subset of normalized input.</summary>
public const string FiAgentSummaryCacheRead = "fi.agent.summary.cache_read";

/// <summary>Non-additive cache-write token summary, a subset of normalized input.</summary>
public const string FiAgentSummaryCacheWrite = "fi.agent.summary.cache_write";

/// <summary>Non-additive reasoning token summary, a subset of normalized output.</summary>
public const string FiAgentSummaryReasoning = "fi.agent.summary.reasoning";

/// <summary>Non-additive cost summary in USD; never place this amount in canonical cost as well unless this span owns the usage.</summary>
public const string FiAgentSummaryCostUsd = "fi.agent.summary.cost_usd";

/// <summary>JSON-encoded array of configured bounded tags, subject to the integration privacy policy.</summary>
public const string FiAgentTags = "fi.agent.tags";

/// <summary>Agent lifecycle event type, for example compaction; not a model invocation.</summary>
public const string FiAgentEvent = "fi.agent.event";

/// <summary>Source input completeness, for example partial; do not present an excerpt as the full model input.</summary>
public const string FiAgentInputCompleteness = "fi.agent.input.completeness";

/// <summary>Provenance of captured content, for example a source transcript; not evidence of native request capture.</summary>
public const string FiAgentContentSource = "fi.agent.content.source";


// ── FI Span Kind ─────────────────────────────────────────────────
public const string FiSpanKind = "fi.span.kind";

Expand Down Expand Up @@ -126,6 +209,7 @@ public static class SemanticConventions

// ── GenAI Performance / Streaming ────────────────────────────────
public const string GenAiClientOperationDuration = "gen_ai.client.operation.duration";
/// <summary>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.</summary>
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";
Expand Down
Original file line number Diff line number Diff line change
@@ -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);
}
}
44 changes: 44 additions & 0 deletions go/a2a/agent_semantic_conventions_test.go
Original file line number Diff line number Diff line change
@@ -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])
}
}
}
68 changes: 68 additions & 0 deletions go/a2a/attributes.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"
)
Loading
Loading