From trajectories to lineage: building better agent telemetry

Aug 27, 2026 · 3 min read · Original on Substack ↗

A conceptual map of how to establish provenance for agent decisions using the existing tools we have today. In agent analysis and tracking, traces and trajectories are becoming well established for understanding a particular decision, or a session of decisions and events that an agent makes.

Cover image for From trajectories to lineage: building better agent telemetry — Cover image from the original post.

In agent analysis and tracking, traces and trajectories are becoming well established for understanding a particular decision, or a session of decisions and events that an agent makes. For single agent systems this is a great starting point. You can build simple analysis models and use trajectories to improve your agent.

But for multi-agent scenarios and long running teams, we need to consider the full lineage of a problem. How did your request for new code materialize in production? If there are multiple agents, versions of agents, and work involved, we need to see the lineage of decisions that were made, by whom (or what), and how.

Agent Lineage is Essentially Data Lineage

In data engineering, we commonly talk about data lineage as a way to understand the relationship of tables, columns, or even rows over time and across systems. If you want to understand a particular field in a database, using lineage you can trace how the field is populated (its calculations), where it was populated from, and do this recursively back to the last source that the lineage system has access to. Column lineage is somewhat common these days, but row level lineage (how did that sales number become 1,000?) is less common due to the computational expense and logging that needs to occur.

Agent lineage and row lineage share the most commonality. I could show you agent lineage as definitions with inputs and outputs (see SIPOC model), but when it comes to understanding particular decisions over time, it doesn’t help me understand why try 11 yielded a bad result while tries 1-10 were fine. We need to spend the time up front to design the system that will capture and chain our series of events together to create the lineage of a particular outcome.

Architecting Agent Lineage

A lineage system for agents relies heavily on existing concepts. We can log the trajectories and spans of a specific agent’s behavior, including seeing the tool calls, and subsequent systems an agent uses.

The hardest part is often tying all of this together.

In many instances, if we are running a harness or a series of events, we can rely on chaining to help connect the dots. We may rely on a handoff where a particular ID is passed on, or where a mapping is created between sessions. Within a multi-agent team contained in a process domain, we may use a UUID (a unique identifier) to tie all of the events together.

In multi-system teams, handoffs and contracts are more likely. When agent A handed off work, did it store a unique identifier that we can find with agent B? If no, we should add metadata in the handoff process.

Ultimately, we want to have an identifier or handoff so we can connect all the dots. Then, we can start to use a full lineage of outcomes to see what is working, and what’s not to optimize the system.

Get Started with Agent Telemetry

Lineage is a powerful tool in agent systems for analysis and improvement. Get started with understanding how to add trajectories to your agent and give unique session ID’s that you can track. I’ve included some starter pieces in this Github repo for agent telemetry.

Code for this essay

agent-telemetry

Bridges the gap between ephemeral LLM reasoning traces and permanent repository commit history by binding OpenTelemetry span IDs, tool-call trajectories, and token budgets directly to AST/Git mutations.

Open in Code

Sample output from a local run

$ uv run python -m agent_telemetry.lineage --commit 9f41c8a2 --format summary
LINEAGE RECORD: commit=9f41c8a2 -> trace_id=4bf92f3577b34da6a3ce929d0e0e4736
MODEL: gemini-3.8-flash · STEPS: 6 · TOOL CALLS: 4 (read_file, edit_file, pytest)
VERIFICATION GATE: PASSED (100% pass rate in 1.42s)

Page metadata

Social card and structured data

The share image, feeds and Schema.org JSON-LD that search engines and AI tools read for this page.

Social card

Card URL: /og/from-trajectories-to-lineage-building.svg

Machine feeds

/llms.txt /llms-full.txt /sitemap.xml /api/agent/spec

Structured data

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Person",
      "@id": "https://davenporter.com/#jason-davenport",
      "name": "Jason Davenport",
      "alternateName": "@davenportjw",
      "jobTitle": "AI & Distributed Systems Architect",
      "description": "Exploring agent-first source control (cosm), trajectory-to-lineage observability, Spanner-backed agent memory consolidation (Electric Sheep), hybrid local/cloud LLM routing, and real-time multiplayer browser simulations on Google Cloud Run.",
      "url": "https://davenporter.com",
      "sameAs": [
        "https://davenporter.substack.com",
        "https://www.linkedin.com/in/davenportjw",
        "https://github.com/davenportjw",
        "https://x.com/davenportjw"
      ]
    },
    {
      "@type": "WebSite",
      "@id": "https://davenporter.com/#website",
      "url": "https://davenporter.com",
      "name": "The Davenporter",
      "description": "Learnings about software, technology, agentic systems, and occasionally home renovation.",
      "publisher": {
        "@id": "https://davenporter.com/#jason-davenport"
      },
      "inLanguage": "en-US"
    },
    {
      "@type": "ImageObject",
      "@id": "https://davenporter.com/writings/from-trajectories-to-lineage-building#primaryimage",
      "url": "https://davenporter.com/og/from-trajectories-to-lineage-building.png",
      "contentUrl": "https://davenporter.com/og/from-trajectories-to-lineage-building.png",
      "width": 1200,
      "height": 630,
      "caption": "Title card for From trajectories to lineage: building better agent telemetry",
      "representativeOfPage": true,
      "creator": {
        "@id": "https://davenporter.com/#jason-davenport"
      },
      "license": "https://creativecommons.org/licenses/by/4.0/",
      "acquireLicensePage": "https://davenporter.com/writings"
    },
    {
      "@type": "WebPage",
      "@id": "https://davenporter.com/writings/from-trajectories-to-lineage-building#webpage",
      "url": "https://davenporter.substack.com/p/from-trajectories-to-lineage-building",
      "name": "From trajectories to lineage: building better agent telemetry | The Davenporter",
      "description": "A conceptual map of how to establish provenance for agent decisions using the existing tools we have today. In agent analysis and tracking, traces and trajectories are becoming well established for understanding a particular decision, or a session of decisions and events that an agent makes.",
      "isPartOf": {
        "@id": "https://davenporter.com/#website"
      },
      "about": {
        "@id": "https://davenporter.com/#jason-davenport"
      },
      "primaryImageOfPage": {
        "@id": "https://davenporter.com/writings/from-trajectories-to-lineage-building#primaryimage"
      },
      "inLanguage": "en-US"
    },
    {
      "@type": "FAQPage",
      "@id": "https://davenporter.com/writings/from-trajectories-to-lineage-building#faq",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "What is \u201cFrom trajectories to lineage: building better agent telemetry\u201d about?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "A conceptual map of how to establish provenance for agent decisions using the existing tools we have today. In agent analysis and tracking, traces and trajectories are becoming well established for understanding a particular decision, or a session of decisions and events that an agent makes."
          }
        }
      ]
    },
    {
      "@type": "BlogPosting",
      "@id": "https://davenporter.com/writings/from-trajectories-to-lineage-building#article",
      "mainEntityOfPage": {
        "@id": "https://davenporter.com/writings/from-trajectories-to-lineage-building#webpage",
        "url": "https://davenporter.substack.com/p/from-trajectories-to-lineage-building"
      },
      "headline": "From trajectories to lineage: building better agent telemetry",
      "alternativeHeadline": "A conceptual map of how to establish provenance for agent decisions using the existing tools we have today",
      "description": "A conceptual map of how to establish provenance for agent decisions using the existing tools we have today. In agent analysis and tracking, traces and trajectories are becoming well established for understanding a particular decision, or a session of decisions and events that an agent makes.",
      "datePublished": "2026-08-27T23:35:33Z",
      "dateModified": "2026-08-27T23:35:33Z",
      "wordCount": 554,
      "keywords": "Agent Telemetry",
      "author": {
        "@id": "https://davenporter.com/#jason-davenport"
      },
      "publisher": {
        "@id": "https://davenporter.com/#jason-davenport"
      },
      "image": {
        "@id": "https://davenporter.com/writings/from-trajectories-to-lineage-building#primaryimage"
      },
      "url": "https://davenporter.substack.com/p/from-trajectories-to-lineage-building"
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://davenporter.com/writings/from-trajectories-to-lineage-building#breadcrumb",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Home",
          "item": "https://davenporter.com/"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Essays",
          "item": "https://davenporter.com/writings"
        },
        {
          "@type": "ListItem",
          "position": 3,
          "name": "From trajectories to lineage: building better agent telemetry",
          "item": "https://davenporter.com/writings/from-trajectories-to-lineage-building"
        }
      ]
    }
  ]
}

From trajectories to lineage: building better agent telemetry

Agent Lineage is Essentially Data Lineage

Architecting Agent Lineage

Get Started with Agent Telemetry

agent-telemetry

Get new posts by email