otel-report-samples

A sample toolkit for collecting, analyzing, and visualizing OpenTelemetry traces from the SpecStory CLI. Includes aa OTel Collector that writes traces to disk, a custom analyzer that generates structured reports from SpecStory traces, and a web dashboard for visualization.

Architecture

specstory-cli (OTEL enabled)
        |
        | gRPC (OTLP)
        v
specstory-collector          Receives traces, writes JSON files to disk
        |
        v
    ./traces/*.json          Raw OTLP trace data as pretty-printed JSON
        |
        v
specstory-analyzer           Parses traces, buckets by time, generates report
        |
        v
    report.json              Structured report (sessions, tokens, exchanges)
        |
        v
    dashboard                Next.js web app for visualization (see below)

Project Structure

otel-report-samples/
├── collector/               # Go: collector + processor + analyzer
│   ├── build/               # Generated OTel Collector source (from OCB)
│   ├── jsonfileprocessor/   # Custom OTel processor: traces/metrics -> JSON files
│   ├── cmd/analyze/         # Trace analyzer CLI
│   ├── collector-config.yaml
│   └── builder-config.yaml
└── dashboard/               # Next.js usage dashboard
    ├── src/app/             # Main dashboard page
    ├── src/lib/             # Chart and styling utilities
    └── public/              # Sample report.json and assets

Prerequisites

• Go 1.22+ (the collector modules require 1.22; the analyzer requires 1.25+)
• Node.js 18+ (for the dashboard)

Collector

The collector is a simple custom OpenTelemetry Collector binary that receives OTLP traces over gRPC and writes them to disk as JSON files. It uses a custom jsonfile processor — there is nothing SpecStory-specific in the collector itself.

Build

cd collector/build
go build -o ../specstory-collector .

Run

cd collector
./specstory-collector --config=collector-config.yaml

This starts the collector listening on 0.0.0.0:4320 (gRPC). Incoming traces are written as pretty-printed JSON to ./traces/. Each trace file is named trace-{timestamp}-{seq}.json.

Sending Traces from SpecStory CLI

With the collector running, point the SpecStory CLI at it. For example:

export OTEL_EXPORTER_OTLP_ENDPOINT="localhost:4320"
export OTEL_SERVICE_NAME="specstory-cli"
export OTEL_ENABLED="true"
export OTEL_RESOURCE_ATTRIBUTES="user_id_hash=user_name,env=dev"
specstory run

See the SpecStory CLI repository for more details on configuring trace export.

Collector Configuration

Edit collector-config.yaml to change:

Setting	Default	Description
receivers.otlp.protocols.grpc.endpoint	0.0.0.0:4320	gRPC listen address
processors.jsonfile.output_dir	./traces	Directory for trace JSON files
processors.jsonfile.metrics_dir	./metrics	Directory for metrics JSON files
processors.jsonfile.pretty_print	true	Indent JSON output

To enable metrics collection, uncomment the metrics pipeline in the config.

Rebuilding with OCB (optional)

The build/ directory contains generated Go source from the OpenTelemetry Collector Builder. It's checked into the repo so you can build the go application without installing OCB. If you need to regenerate it (e.g., to change OTel component versions):

cd collector
builder --config=builder-config.yaml

Analyzer

The analyzer reads trace JSON files produced by the collector and generates a structured report. It understands SpecStory's trace format — span names like process_session and process_exchange, and attributes like specstory.session.id, token counts, and exchange metadata.

Build

cd collector
go build -o specstory-analyzer ./cmd/analyze

Run

# Basic usage — reads ./traces, writes report to stdout
./specstory-analyzer

# Write report to a file
./specstory-analyzer --output report.json

# Custom traces directory and bucket size
./specstory-analyzer --traces-dir ./my-traces --bucket-size 15m --output report.json

# Skip LLM summary generation
./specstory-analyzer --no-summaries --output report.json

Flags

Flag	Default	Description
--traces-dir	./traces	Directory containing trace JSON files
--bucket-size	5m	Time bucket size for aggregation (e.g., 1m, 5m, 15m)
--output	stdout	Output file path for the report
--no-summaries	false	Skip LLM-based session summary generation
--summarize-session		Re-summarize a single session by ID (prefix match supported)
--update-report	false	Update the report file in place (use with --summarize-session)

LLM Summaries (optional)

The analyzer can generate short natural-language summaries for each coding session using the Anthropic API. This is optional — if ANTHROPIC_API_KEY is not set, summaries are skipped automatically.

To enable summaries, set your API key via environment variable or create a collector/.env file:

export ANTHROPIC_API_KEY=sk-ant-...

Or:

# collector/.env
ANTHROPIC_API_KEY=sk-ant-...

Report Structure

The generated report.json contains:

• report_period — start/end timestamps
• users[] — per-user stats: session activity buckets, exchange counts, token usage, agent activity
• global — aggregate stats across all users
• sessions{} — per-session detail: project path, agent, exchange-level metadata (prompts, tools used, token counts), and optional LLM summary

Dashboard

A Next.js web app that visualizes report.json with interactive charts and session detail drill-downs.

Setup

cd dashboard
npm install

Run

npm run dev

Opens at http://localhost:3000.

Using Your Own Data

The dashboard ships with a sample public/report.json. To visualize your own traces, generate a report with the analyzer and copy it in:

cd collector
./specstory-analyzer --output ../dashboard/public/report.json

Then restart the dev server (or rebuild for production).

Features

• Concurrent Sessions — session activity over time in 5-minute buckets
• Exchange Activity — exchanges per user over time
• Token Usage — input/output/cache tokens stacked by time bucket
• Agent Activity — exchanges broken down by agent type
• User Details — summary stats table with percentile filtering (P50/P75/P95)
• Session Cards — hover/click for per-session detail including prompts, tools used, and token counts

Production Build

npm run build
npm run start

Datadog Dashboard

A pre-built Datadog dashboard is included at dashboard/SpecStoryOTelDashboard--Datadog.json. It visualizes SpecStory OTEL metrics directly in Datadog (useful if you're sending traces to Datadog instead of or in addition to the local collector).

To import it, open any dashboard in Datadog, click the settings cog, and select Import Dashboard JSON. See the Datadog docs for details.

It relies on metrics generated from SpecStory OTel spans, using APM→Generate Metrics:

License

The SpecStory CLI is licensed under the Apache 2.0 open source license.

Copyright 2025-2026 by SpecStory, Inc., All Rights Reserved.

SpecStory® is a registered trademark of SpecStory, Inc.