CubeAPM

What it coversCopy Anchor Link

CubeAPM is the main application-telemetry source: inventory services, find error traces, inspect a trace waterfall, correlate logs, measure error and latency signals, and map how a failure moves between services.

ConnectCopy Anchor Link

One CubeAPM server usually holds every environment. Make one shared connection and give it the label each environment uses inside CubeAPM:

reckon connect cubeapm --org acme --provider cubeapm --label prod=PROD --label uat=UAT

Fill in ~/.reckon/orgs/acme/secrets/cubeapm.env:

CUBEAPM_SERVER=cube.example.com
CUBEAPM_EMAIL=user@example.com
CUBEAPM_PASSWORD=replace_me

CUBEAPM_QUERY_PORT, CUBEAPM_INGEST_PORT and CUBEAPM_ADMIN_PORT are optional for deployments that differ from the defaults. Instead of the file, you can run reckon login cubeapm in your own terminal: it runs cubeapm login and keeps the profile in that connection's private config.

Add a label later by running reckon connect again on the same name, for example reckon connect cubeapm --org acme --label dev=DEV. If each environment has its own CubeAPM server, use --for-env connections instead.

reckon verify cubeapm runs cubeapm metrics query 1 -o json.

Environment labelsCopy Anchor Link

A shared server holds every environment, so every read must select the active environment's label (RECKON.md in the org folder lists them). Reckon enforces this:

• Traces: traces search and traces services get --env <label> added when you leave it out. Any other value is refused.
• Metrics and logs: metrics query, metrics query-range, logs query, logs hits and logs stats must select the label with a positive selector: {env="<label>"} in PromQL, env:<label> or --stream '{env="<label>"}' in LogsQL. or and unless are refused unless --stream itself selects the label and the query has no | pipe, so the filter covers the whole query. A trailing -- is refused, because flags after it are ignored.
• Anything else: a selector naming another environment's label, or excluding the active one (env!=), is refused, including --tags environment=.... Put the full command first (metrics query ...).

These checks stop mistakes, not a determined query: keep queries simple.

Label keys depend on your instrumentation: some metric families use cube.environment instead of env. Check with metrics label-values and logs field-names / logs field-values. traces get, traces operations and traces dependencies take no environment; attribute their results to the environment the trace came from.

Read-only contractCopy Anchor Link

Reckon runs cubeapm with CUBEAPM_READ_ONLY=true and CUBEAPM_NO_INPUT=true. It refuses --server, --email, --password, the port flags, --profile, --read-only, --no-input and --verbose, and the login, config, update, ingest and logs delete commands.

Key commandsCopy Anchor Link

reckon run cubeapm -- traces services --env PROD --last 1h -o json
reckon run cubeapm -- traces search --service checkout --env PROD --status error --last 1h -o json
reckon run cubeapm -- traces get <trace-id> --last 2h -o json
reckon run cubeapm -- logs query 'error' --service checkout --stream '{env="PROD"}' --last 1h -o json
reckon run cubeapm -- logs hits --query '_stream:{env="PROD"} AND level:error' --last 6h --step 15m -o json
reckon run cubeapm -- metrics query-range 'sum(rate(http_requests_total{env="PROD",status=~"5.."}[5m]))' --last 1h --step 60s -o json
reckon run cubeapm -- traces dependencies --last 1h -o json

logs query -o json prints a stream of JSON objects, not one JSON value. Quote PromQL and LogsQL so the shell keeps braces and regex operators intact.

LinksCopy Anchor Link

• CubeAPM documentation
• cubeapm-cli documentation
• cubeapm-cli source