Quickstart

Send your first telemetry to PackDB and confirm it landed — in a few minutes, with an OpenTelemetry collector or a single curl.

What you'll do

1Create your account — Sign up with email or GitHub
2Connect your data — Configure your application to send telemetry
3Verify ingestion — Confirm data is flowing
4Start exploring — Query and visualize your telemetry

1. Mint an API key

Ingestion authenticates with a long-lived machine key (packdb_…). Create one from API keys in your workspace settings, then send it as the X-API-Key header. The key carries your tenant scope, so no tenant header is needed.

Browser session tokens (Authorization: Bearer …) are not the right credential here — a collector or Grafana datasource needs a machine key.

2. Send telemetry

Point an OpenTelemetry collector at PackDB. The same exporter handles metrics, logs, and traces.

yaml

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:

exporters:
  otlphttp/packdb:
    endpoint: "https://ingest.packdb.io"
    headers:
      x-api-key: "<YOUR_PACKDB_API_KEY>"
    compression: gzip

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/packdb]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/packdb]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/packdb]

No collector handy? Smoke-test the ingest path with a single curl. It writes one gauge sample, demo_metric=42, tagged service.name=curl-demo.

bash

# OTLP HTTP + JSON. Writes a single Gauge sample (demo_metric=42)
# tagged with service.name=curl-demo. The timeUnixNano is "now"; the
# server accepts anything within the ingest time window.
NOW_NS=$(date +%s)000000000
curl -X POST "https://ingest.packdb.io/v1/metrics" \
  -H "X-API-Key: <YOUR_PACKDB_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceMetrics": [{
      "resource": {
        "attributes": [
          {"key": "service.name", "value": {"stringValue": "curl-demo"}}
        ]
      },
      "scopeMetrics": [{
        "metrics": [{
          "name": "demo_metric",
          "gauge": {
            "dataPoints": [{
              "asDouble": 42,
              "timeUnixNano": "'"$NOW_NS"'"
            }]
          }
        }]
      }]
    }]
  }'

3. Verify ingestion

Read the sample back. OpenTelemetry's service.name resource attribute becomes the PromQL label service_name (dots become underscores).

bash

curl -G "https://api.packdb.io/api/v1/query" \
  --data-urlencode 'query=demo_metric{service_name="curl-demo"}' \
  -H "X-API-Key: <YOUR_PACKDB_API_KEY>"

Prefer SQL? The same sample reads back over REST — OTel metrics land one table per metric under the metrics schema, and the endpoint speaks a PostgreSQL date_bin() dialect (also available over FlightSQL).

bash

# POST /api/v1/sql with {"q": "<sql>"} — same X-API-Key machine auth.
curl -X POST "https://api.packdb.io/api/v1/sql" \
  -H "X-API-Key: <YOUR_PACKDB_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"q": "SELECT timestamp, value, service_name FROM metrics.demo_metric ORDER BY timestamp DESC LIMIT 5"}'

4. Explore

Open your dashboard to query metrics with PromQL, search logs with LogQL, and search traces with TraceQL. To visualize in Grafana, see the Grafana guide.

Nothing showing up? The troubleshooting guide covers the usual auth, ingest, and query gotchas.