entity_mapping.md

An example of how AgentOps components could map to OpenTelemetry concepts:

1. Core Mapping

graph LR
    subgraph AgentOps
        A[Session] --> B[Events]
        B --> C[LLMEvent]
        B --> D[ActionEvent]
        B --> E[ToolEvent]
    end

    subgraph OpenTelemetry
        F[Trace] --> G[Spans]
        G --> H[LLM Spans]
        G --> I[Action Spans]
        G --> J[Tool Spans]
        K[Metrics] --> L[LLM Metrics]
    end

    A -.->|Maps to| F
    C -.->|Maps to| H
    D -.->|Maps to| I
    E -.->|Maps to| J

Loading

Let's look at specific examples:

1. Session to Trace

# When AgentOps starts a session:
class Session:
    def __init__(self):
        # Create root span for the session
        self.trace = tracer.start_span(
            name="agentops.session",
            attributes={
                "session.id": self.session_id,
                "agent.id": self.agent_id
            }
        )

2. LLMEvent to Span

# When AgentOps records an LLM event:
class LLMEvent:
    def to_span(self):
        return tracer.start_span(
            name="llm.completion",
            attributes={
                "llm.model": self.model,
                "llm.tokens.prompt": self.prompt_tokens,
                "llm.tokens.completion": self.completion_tokens,
                "llm.cost": self.cost
            }
        )

3. LLM Metrics

# In LlmTracker:
class LlmTracker:
    def __init__(self):
        self.calls_counter = meter.create_counter(
            name="llm.calls",
            description="Number of LLM API calls"
        )
        
        self.token_histogram = meter.create_histogram(
            name="llm.tokens",
            description="Distribution of token usage"
        )