honeycomb-trace-spans

A command-line tool to retrieve all spans in a trace from Honeycomb.

Installation

You can install this package globally:

npm install -g honeycomb-trace-spans

Or use it with npx:

npx honeycomb-trace-spans --trace-id <trace_id>

Usage

Get a Honeycomb API Key for your team and environment.

export HONEYCOMB_API_KEY=your_api_key
honeycomb-trace-spans --trace-id <trace_id> [--time-range <seconds>]
honeycomb-trace-spans --trace-id <trace_id> --start-time <unix_timestamp> --end-time <unix_timestamp>

Parameters

• --trace-id: The trace ID to retrieve spans for (required)
• --time-range: Time range in seconds to look for spans (optional, default: 3600 seconds/1 hour)
• --start-time: Start time as Unix timestamp in seconds (optional, must be used with --end-time)
• --end-time: End time as Unix timestamp in seconds (optional, must be used with --start-time)

Environment Variables

• HONEYCOMB_API_KEY: Your Honeycomb API key (required)
• HONEYCOMB_API_ENDPOINT: Custom API endpoint (optional, default: https://api.honeycomb.io)

Examples

# Set your Honeycomb API key
export HONEYCOMB_API_KEY=your_api_key

# Retrieve spans for a trace with default time range (1 hour)
honeycomb-trace-spans --trace-id abcd1234efgh5678

# Retrieve spans for a trace with a custom time range (last 24 hours)
honeycomb-trace-spans --trace-id abcd1234efgh5678 --time-range 86400

# Retrieve spans for a trace with an absolute time range
honeycomb-trace-spans --trace-id abcd1234efgh5678 --start-time 1617235200 --end-time 1617321600

# With an absolute time range from yesterday to now
honeycomb-trace-spans --trace-id abcd1234efgh5678 --start-time $(date -v-1d +%s) --end-time $(date +%s)

Output

The script outputs structured JSON data that's optimized for agent consumption, while still providing the trace URL for human use.

Example output:

{
  "summary": {
    "traceId": "abcd1234efgh5678",
    "spanCount": 16,
    "services": ["service-a", "service-b", "service-c"],
    "rootSpans": 1,
    "timeRange": {
      "start": 1617235200,
      "end": 1617321600
    },
    "traceUrl": "https://ui.honeycomb.io/team/environments/env/trace?trace_id=abcd1234efgh5678&trace_start_ts=1617235200&trace_end_ts=1617321600"
  },
  "spans": [
    {
      "spanId": "span1",
      "parentId": "ROOT",
      "name": "request",
      "service": "service-a",
      "duration": 100.5,
      "attributes": {}
    }
    // ... more spans ...
  ]
}

License

MIT