Telemetry Collection

{
  "schema": 1,
  "installation_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-30T14:22:00Z",
  "cli_version": "0.1.0",
  "os": "linux",
  "arch": "x86_64",
  "event": {
    "type": "command_run",
    "command_category": "tool_invoke",
    "transport": "streamable_http",
    "json_output": false,
    "background": false,
    "timeout_override": false,
    "profile_active": true,
    "daemon_active": false,
    "ad_hoc": false,
    "outcome": "success",
    "duration_ms": 342
  }
}

telemetry:
  enabled: false

--no-telemetry flag > MCP2CLI_TELEMETRY env > DO_NOT_TRACK env > config enabled field

~/.local/share/mcp2cli/telemetry.ndjson

// collector.js — receives telemetry batches and appends to a file
const http = require('http');
const fs = require('fs');

const LOG_FILE = '/var/log/mcp2cli-telemetry.ndjson';

http.createServer((req, res) => {
  if (req.method !== 'POST') {
    res.writeHead(405).end();
    return;
  }
  let body = '';
  req.on('data', chunk => body += chunk);
  req.on('end', () => {
    try {
      const events = JSON.parse(body);
      const lines = events.map(e => JSON.stringify(e)).join('\n') + '\n';
      fs.appendFileSync(LOG_FILE, lines);
      res.writeHead(202).end();
    } catch {
      res.writeHead(400).end();
    }
  });
}).listen(9090, () => console.log('Telemetry collector on :9090'));

telemetry:
  enabled: true
  endpoint: "https://your-collector.example.com/v1/events"
  batch_size: 25

POST /v1/events HTTP/1.1
Content-Type: application/json

[
  {"schema":1,"installation_id":"...","event":{"type":"command_run",...}},
  {"schema":1,"installation_id":"...","event":{"type":"command_run",...}}
]

# posthog-relay.py — translates mcp2cli events to PostHog capture API
import json, sys, requests

POSTHOG_HOST = "https://your-posthog.example.com"
API_KEY = "phc_your_project_api_key"

for line in sys.stdin:
    event = json.loads(line)
    kind = event["event"]
    props = {
        "cli_version": event["cli_version"],
        "os": event["os"],
        "arch": event["arch"],
    }
    if kind.get("type") == "command_run":
        props.update({
            "command_category": kind["command_category"],
            "transport": kind["transport"],
            "outcome": kind["outcome"],
            "duration_ms": kind["duration_ms"],
            "json_output": kind["json_output"],
            "background": kind["background"],
            "ad_hoc": kind["ad_hoc"],
        })
    requests.post(f"{POSTHOG_HOST}/capture/", json={
        "api_key": API_KEY,
        "event": kind.get("type", "unknown"),
        "distinct_id": event["installation_id"],
        "properties": props,
        "timestamp": event["timestamp"],
    })

CREATE TABLE mcp2cli_telemetry (
    id BIGSERIAL PRIMARY KEY,
    received_at TIMESTAMPTZ DEFAULT now(),
    schema_version INT NOT NULL,
    installation_id UUID NOT NULL,
    event_timestamp TIMESTAMPTZ NOT NULL,
    cli_version TEXT NOT NULL,
    os TEXT NOT NULL,
    arch TEXT NOT NULL,
    event_type TEXT NOT NULL,
    command_category TEXT,
    transport TEXT,
    json_output BOOLEAN,
    background BOOLEAN,
    timeout_override BOOLEAN,
    profile_active BOOLEAN,
    daemon_active BOOLEAN,
    ad_hoc BOOLEAN,
    outcome TEXT,
    duration_ms BIGINT
);

CREATE INDEX idx_telemetry_ts ON mcp2cli_telemetry (event_timestamp);
CREATE INDEX idx_telemetry_category ON mcp2cli_telemetry (command_category);
CREATE INDEX idx_telemetry_installation ON mcp2cli_telemetry (installation_id);

-- Top 10 most-used commands
SELECT command_category, COUNT(*) as uses
FROM mcp2cli_telemetry
WHERE event_type = 'command_run'
GROUP BY command_category
ORDER BY uses DESC
LIMIT 10;

-- Error rate by command category
SELECT
  command_category,
  COUNT(*) FILTER (WHERE outcome = 'error') AS errors,
  COUNT(*) AS total,
  ROUND(100.0 * COUNT(*) FILTER (WHERE outcome = 'error') / COUNT(*), 1) AS error_pct
FROM mcp2cli_telemetry
WHERE event_type = 'command_run'
GROUP BY command_category
ORDER BY error_pct DESC;

-- Feature adoption over time (weekly)
SELECT
  date_trunc('week', event_timestamp) AS week,
  COUNT(*) FILTER (WHERE json_output) AS json_users,
  COUNT(*) FILTER (WHERE background) AS background_users,
  COUNT(*) FILTER (WHERE daemon_active) AS daemon_users,
  COUNT(*) FILTER (WHERE ad_hoc) AS adhoc_users,
  COUNT(*) FILTER (WHERE profile_active) AS profile_users
FROM mcp2cli_telemetry
WHERE event_type = 'command_run'
GROUP BY week
ORDER BY week;

-- P50/P95/P99 latency by command
SELECT
  command_category,
  PERCENTILE_CONT(0.50) WITHIN GROUP (ORDER BY duration_ms) AS p50_ms,
  PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY duration_ms) AS p95_ms,
  PERCENTILE_CONT(0.99) WITHIN GROUP (ORDER BY duration_ms) AS p99_ms
FROM mcp2cli_telemetry
WHERE event_type = 'command_run' AND outcome = 'success'
GROUP BY command_category;

-- Unique installations per week
SELECT
  date_trunc('week', event_timestamp) AS week,
  COUNT(DISTINCT installation_id) AS active_installs
FROM mcp2cli_telemetry
GROUP BY week
ORDER BY week;

-- OS/Arch distribution
SELECT os, arch, COUNT(DISTINCT installation_id) AS installs
FROM mcp2cli_telemetry
GROUP BY os, arch
ORDER BY installs DESC;

CREATE TABLE mcp2cli_telemetry (
    installation_id UUID,
    event_timestamp DateTime64(3),
    cli_version LowCardinality(String),
    os LowCardinality(String),
    arch LowCardinality(String),
    event_type LowCardinality(String),
    command_category LowCardinality(String),
    transport LowCardinality(String),
    outcome LowCardinality(String),
    duration_ms UInt64,
    json_output Bool,
    background Bool,
    ad_hoc Bool
) ENGINE = MergeTree()
ORDER BY (event_timestamp, installation_id);

CREATE EXTERNAL TABLE mcp2cli_telemetry (
    schema INT,
    installation_id STRING,
    timestamp STRING,
    cli_version STRING,
    os STRING,
    arch STRING,
    event STRUCT<
        type: STRING,
        command_category: STRING,
        transport: STRING,
        outcome: STRING,
        duration_ms: BIGINT,
        json_output: BOOLEAN,
        background: BOOLEAN,
        ad_hoc: BOOLEAN
    >
)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
LOCATION 's3://your-bucket/telemetry/';