API Reference

REST API endpoints exposed by Telegen.

Overview

Telegen exposes a REST API for health checks, metrics, and status information. By default, the API listens on port 19090.

self_telemetry:
  listen: ":19090"

Health Endpoints

GET /healthz

Liveness probe endpoint.

Response:

{
  "status": "ok"
}

Status Codes:

Code Description
200 Healthy
503 Unhealthy

Example:

curl http://localhost:19090/healthz

GET /ready

Readiness probe endpoint.

Response:

{
  "status": "ready",
  "checks": {
    "ebpf": "ok",
    "otlp": "ok",
    "discovery": "ok"
  }
}

Failed Check Response:

{
  "status": "not_ready",
  "checks": {
    "ebpf": "ok",
    "otlp": "failed: connection refused",
    "discovery": "ok"
  }
}

Status Codes:

Code Description
200 Ready
503 Not ready

Example:

curl http://localhost:19090/ready

Metrics Endpoint

GET /metrics

Prometheus metrics endpoint.

Response: Prometheus text format

# HELP telegen_spans_collected_total Total spans collected
# TYPE telegen_spans_collected_total counter
telegen_spans_collected_total 12345

# HELP telegen_process_resident_memory_bytes Memory usage
# TYPE telegen_process_resident_memory_bytes gauge
telegen_process_resident_memory_bytes 134217728
...

Content-Type: text/plain; version=0.0.4

Example:

curl http://localhost:19090/metrics

Status Endpoints

GET /status

Detailed status information.

Response:

{
  "version": "3.0.0",
  "commit": "abc1234",
  "built": "2024-01-15T10:00:00Z",
  "uptime": "24h15m30s",
  "mode": "agent",
  "host": {
    "name": "node-1",
    "os": "linux",
    "arch": "amd64",
    "kernel": "5.15.0-91-generic"
  },
  "ebpf": {
    "enabled": true,
    "programs_loaded": 15,
    "maps_created": 25,
    "ringbuf_size": 16777216
  },
  "profiling": {
    "enabled": true,
    "sample_rate": 99,
    "profiles_collected": 1234
  },
  "export": {
    "endpoint": "otel-collector:4317",
    "connected": true,
    "last_export": "2024-01-15T10:30:00Z",
    "spans_exported": 123456,
    "metrics_exported": 789012
  },
  "discovery": {
    "kubernetes": true,
    "docker": true,
    "pods_discovered": 45,
    "containers_discovered": 78
  }
}

Status Codes:

Code Description
200 Success

Example:

curl http://localhost:19090/status

GET /status/ebpf

eBPF-specific status.

Response:

{
  "enabled": true,
  "programs": [
    {
      "name": "trace_http_request",
      "type": "kprobe",
      "attached": true,
      "id": 123
    },
    {
      "name": "trace_tcp_connect",
      "type": "tracepoint",
      "attached": true,
      "id": 124
    }
  ],
  "maps": [
    {
      "name": "connection_map",
      "type": "hash",
      "entries": 1234,
      "max_entries": 100000
    }
  ],
  "ringbuf": {
    "size": 16777216,
    "events_received": 1234567,
    "events_lost": 0
  }
}

Example:

curl http://localhost:19090/status/ebpf

GET /status/export

Export status.

Response:

{
  "endpoint": "otel-collector:4317",
  "protocol": "grpc",
  "tls": false,
  "compression": "gzip",
  "connected": true,
  "last_export": "2024-01-15T10:30:00Z",
  "last_error": null,
  "queues": {
    "traces": {
      "size": 128,
      "capacity": 10000,
      "exported": 123456,
      "dropped": 0
    },
    "metrics": {
      "size": 64,
      "capacity": 5000,
      "exported": 789012,
      "dropped": 0
    },
    "logs": {
      "size": 256,
      "capacity": 10000,
      "exported": 456789,
      "dropped": 0
    }
  }
}

Example:

curl http://localhost:19090/status/export

GET /status/discovery

Discovery status.

Response:

{
  "kubernetes": {
    "enabled": true,
    "connected": true,
    "cluster": "prod-cluster",
    "namespace": "monitoring",
    "pods_watched": 145,
    "services_watched": 32
  },
  "docker": {
    "enabled": true,
    "connected": true,
    "containers": 12
  },
  "cloud": {
    "provider": "aws",
    "region": "us-east-1",
    "instance_id": "i-1234567890abcdef0"
  },
  "discovered_services": [
    {
      "name": "frontend",
      "namespace": "default",
      "instances": 3,
      "ports": [80, 443]
    },
    {
      "name": "api",
      "namespace": "default",
      "instances": 2,
      "ports": [8080]
    }
  ]
}

Example:

curl http://localhost:19090/status/discovery

Configuration Endpoint

GET /config

Current configuration (sanitized).

Response:

{
  "mode": "agent",
  "otlp": {
    "endpoint": "otel-collector:4317",
    "insecure": true,
    "compression": "gzip"
  },
  "agent": {
    "ebpf": {
      "enabled": true,
      "network": {
        "enabled": true
      }
    },
    "profiling": {
      "enabled": true,
      "sample_rate": 99
    }
  }
}

Note: Sensitive values (passwords, tokens) are redacted.

Example:

curl http://localhost:19090/config

Debug Endpoints

These endpoints are available when debug mode is enabled.

GET /debug/pprof/

Go pprof endpoints.

Available Profiles:

Path Description
/debug/pprof/ Index
/debug/pprof/heap Heap profile
/debug/pprof/goroutine Goroutine stacks
/debug/pprof/threadcreate Thread creation
/debug/pprof/block Blocking profile
/debug/pprof/mutex Mutex contention
/debug/pprof/profile CPU profile
/debug/pprof/trace Execution trace

Examples:

# CPU profile (30 seconds)
curl http://localhost:19090/debug/pprof/profile?seconds=30 > cpu.pprof

# Heap profile
curl http://localhost:19090/debug/pprof/heap > heap.pprof

# Goroutine stacks
curl http://localhost:19090/debug/pprof/goroutine?debug=2

# Analyze with go tool
go tool pprof cpu.pprof

GET /debug/vars

Runtime variables (expvar).

Response:

{
  "cmdline": ["telegen", "--config", "/etc/telegen/config.yaml"],
  "memstats": {
    "Alloc": 12345678,
    "TotalAlloc": 987654321,
    "Sys": 23456789,
    "NumGC": 123
  }
}

Example:

curl http://localhost:19090/debug/vars

Admin Endpoints

POST /admin/reload

Reload configuration.

Request: None

Response:

{
  "status": "ok",
  "message": "Configuration reloaded"
}

Status Codes:

Code Description
200 Success
400 Invalid configuration
500 Reload failed

Example:

curl -X POST http://localhost:19090/admin/reload

POST /admin/flush

Flush all queues.

Response:

{
  "status": "ok",
  "flushed": {
    "traces": 128,
    "metrics": 64,
    "logs": 256
  }
}

Example:

curl -X POST http://localhost:19090/admin/flush

Authentication

When authentication is enabled:

self_telemetry:
  auth:
    enabled: true
    bearer_token: "${API_TOKEN}"

Include the token in requests:

curl -H "Authorization: Bearer ${API_TOKEN}" http://localhost:19090/status

Rate Limiting

The API may be rate-limited:

self_telemetry:
  rate_limit:
    enabled: true
    requests_per_second: 100

When rate limited, the API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 1

CORS

For browser access, CORS can be enabled:

self_telemetry:
  cors:
    enabled: true
    allowed_origins:
      - "http://localhost:3000"

Error Responses

Standard Error Format

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {
    "field": "additional context"
  }
}

Error Codes

Code Description
invalid_request Malformed request
not_found Resource not found
unauthorized Authentication required
forbidden Permission denied
internal_error Server error
service_unavailable Temporarily unavailable

API Versioning

Current API version: v1

The API is currently unversioned. Future breaking changes will introduce versioned paths:

/api/v1/status
/api/v2/status

OpenAPI Specification

OpenAPI spec is available at:

curl http://localhost:19090/openapi.json

Next Steps

Back to top ↑