OpenTelemetry Span Attributes in ContextForge¶

This document lists all span attributes created in the ContextForge codebase, organized by category with real-world code-level examples.

CUSTOMIZING SPAN ATTRIBUTES¶

ContextForge provides the SpanAttributeCustomizer plugin to customize OpenTelemetry span attributes at runtime. This allows you to:

• Add global attributes to all spans (e.g., environment, region, team)
• Override attributes per tool for specific tools
• Transform attribute values (hash for PII, uppercase, lowercase, truncate)
• Add conditional attributes based on tool name or context
• Remove sensitive attributes for privacy/compliance

Setup¶

1. Enable the plugin in plugins/config.yaml:

plugins:
  - name: "SpanAttributeCustomizer"
    kind: "plugins.span_attribute_customizer.span_attribute_customizer.SpanAttributeCustomizerPlugin"
    hooks: ["tool_pre_invoke", "tool_post_invoke", "resource_pre_fetch", "resource_post_fetch"]
    mode: "permissive"
    priority: 10
    config:
      global_attributes:
        environment: "production"
        region: "us-east-1"
        team: "platform"
      tool_overrides:
        weather_api:
          attributes:
            service: "weather"
            cost_center: "engineering"
      transformations:
        - field: "user.email"
          operation: "hash"
      conditions:
        - when: "tool.name == \"sensitive_operation\""
          add:
            audit_required: true
            compliance_level: "high"
      remove_attributes:
        - "internal_debug_info"

1. Enable plugins in .env:

PLUGINS_ENABLED=true
PLUGINS_CONFIG_FILE=plugins/config.yaml

1. Restart the gateway

For detailed configuration options, see plugins/span_attribute_customizer/README.md.

TOOL INVOCATION ATTRIBUTES¶

Core Tool Attributes¶

Tool Lookup Attributes¶

Tool Gateway Call Attributes¶

Tool Post-Process Attributes¶

MCP CLIENT ATTRIBUTES¶

MCP Client Call Attributes¶

MCP Client Initialize Attributes¶

MCP Client Request Attributes¶

MCP Client Response Attributes¶

PLUGIN FRAMEWORK ATTRIBUTES¶

Plugin Chain Attributes¶

Plugin Execution Attributes¶

Plugin Hook Attributes¶

PROMPT ATTRIBUTES¶

Prompt Render Attributes¶

RESOURCE ATTRIBUTES¶

Resource Invocation Attributes¶

Resource Read Attributes¶

Resource Get Attributes¶

GATEWAY ATTRIBUTES¶

Gateway Health Check Attributes¶

A2A (AGENT-TO-AGENT) ATTRIBUTES¶

A2A Invocation Attributes¶

LLM PROXY ATTRIBUTES¶

LLM Request Attributes¶

LLM Usage Attributes¶

ROOT SERVICE ATTRIBUTES¶

Root List Attributes¶

USER & TEAM CONTEXT ATTRIBUTES¶

Identity Attributes¶

Authentication Attributes¶

LANGFUSE-SPECIFIC ATTRIBUTES¶

Langfuse Identity Attributes¶

Langfuse Trace Attributes¶

Langfuse Input/Output Attributes¶

REQUEST CONTEXT ATTRIBUTES¶

Correlation & Request Attributes¶

Baggage Attributes¶

HTTP REQUEST ATTRIBUTES (ObservabilityMiddleware)¶

HTTP Request Attributes¶

HTTP Response Attributes¶

ERROR ATTRIBUTES¶

Error Attributes¶

SUMMARY BY CATEGORY¶

Tool Invocation (12 attributes)¶

• Core: tool.name, tool.id, tool.integration_type, tool.gateway_id, arguments_count, has_headers, success, duration.ms
• Lookup: tool.name, tool.id, tool.integration_type
• Gateway Call: tool.name, tool.id, tool.integration_type

MCP Protocol (15 attributes)¶

• Call: mcp.tool.name, contextforge.tool.id, contextforge.gateway_id, contextforge.runtime, contextforge.transport, network.protocol.name, server.address, server.port, url.path, url.full
• Initialize: contextforge.transport, contextforge.runtime
• Request: mcp.tool.name, contextforge.tool.id, contextforge.gateway_id, contextforge.runtime
• Response: mcp.tool.name, contextforge.tool.id, contextforge.gateway_id, contextforge.runtime, upstream.response.success

Plugin Framework (13 attributes)¶

• Chain: plugin.chain.stopped, plugin.chain.stopped_by, plugin.executed_count, plugin.skipped_count
• Execution: plugin.had_violation, plugin.modified_payload, plugin.continue_processing, plugin.stopped_chain
• Hook: plugin.hook.invoke, plugin.hook.type, plugin.name, plugin.mode, plugin.priority

Prompt (11 attributes)¶

• prompt.id, arguments_count, user, server_id, tenant_id, request_id, success, duration.ms, langfuse.observation.prompt.name, langfuse.observation.prompt.version, messages.count

Resource (11 attributes)¶

• Invocation: resource.name, resource.id, resource.uri, gateway.transport, gateway.url
• Read: resource.uri, user, server_id, request_id, http.url, resource.type
• Get: resource.id, include_inactive

Gateway (4 attributes)¶

• gateway.count, check.type, check.duration_ms, check.completed

A2A (5 attributes)¶

• a2a.agent.name, a2a.agent.id, a2a.agent.url, a2a.agent.type, a2a.interaction_type

LLM Proxy (11 attributes)¶

• Request: langfuse.observation.type, gen_ai.system, gen_ai.request.model, gen_ai.response.model, llm.provider.id, llm.provider.type, llm.model.id, llm.stream
• Usage: gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.usage.total_tokens

Root Service (1 attribute)¶

• root.count

User & Team Context (5 attributes)¶

• Identity: user.email, user.is_admin, team.scope, team.name
• Auth: auth.method

Langfuse Integration (9 attributes)¶

• Identity: langfuse.user.id, langfuse.session.id, langfuse.environment
• Trace: langfuse.trace.tags, langfuse.trace.name, langfuse.observation.level, langfuse.observation.status_message
• I/O: langfuse.observation.input, langfuse.observation.output

Request Context (5 attributes)¶

• correlation_id, request_id, server_id, tenant_id, baggage.{key}

HTTP (11 attributes)¶

• Request: http.request.method, http.route, url.path, url.query, network.protocol.version, server.address, server.port, client.address, client.port, user_agent.original, correlation_id
• Response: http.response.status_code, http.status_code

Error Handling (3 attributes)¶

• error, error.type, error.message

Total: 116 unique span attributes across all categories