Developer telemetry

Developer telemetry is a read-only, project-scoped query surface. It uses the same project selection order as every other project command: global --project, PHOTON_PROJECT_ID, then the stored active project. Browse the automatic command reference.

Logs and traces

Log and trace lists require an explicit RFC 3339 --from and --to. Timestamps must include seconds, may use Z or a numeric offset, and may contain at most three fractional digits. The CLI normalizes valid timestamps to UTC before the SDK request, and --from must be earlier than --to.

photon project telemetry log list \
  --from 2026-08-24T01:00:00.000Z \
  --to 2026-08-24T02:00:00.000Z \
  --severity-text ERROR \
  --minimum-severity-number 17 \
  --body-contains timeout \
  --trace-id 0123456789abcdef0123456789abcdef \
  --limit 50 \
  --offset 0

photon project telemetry trace list \
  --from 2026-08-24T01:00:00Z \
  --to 2026-08-24T02:00:00Z \
  --request-id request_calls_123 \
  --route /v1/calls \
  --http-method GET \
  --type request \
  --http-status-class 5xx \
  --minimum-duration-ms 250

Log filters are:

--severity-text
--minimum-severity-number from 1 through 24
--body-contains
--trace-id, a 32-character lowercase hexadecimal Trace ID
--span-id, a 16-character lowercase hexadecimal Span ID

Trace-list filters are:

--request-id, from 1 through 128 characters
--route, the matched route template such as /v1/calls
--http-method
--http-status-code, from 100 through 599
--http-status-class, one of 1xx through 5xx
--status, one of Ok, Error, or Unset
--type, either request or delivery
--minimum-duration-ms, matched against the Span’s own duration

--type matches the root span’s photon.trace.type attribute. The CLI accepts only request and delivery. --status matches the OpenTelemetry status of the trace’s entry Span rather than the HTTP one. A successful request stays Unset, because the convention reserves Ok for work that explicitly declares success. --status Error finds requests that returned a 5xx or threw; an error recorded on a business Span deeper in the trace does not change the entry Span and is not visible to this filter. The list reads the Spans that begin a trace, so each row is one trace. Both list commands default to --limit 30 --offset 0. Limits range from 1 through 100; offsets range from 0 through 1000000. Each invocation reads exactly one page. It does not infer a recent window, calculate a total, follow another page, or create a client cursor. Human log output includes time, severity, service, a bounded one-line message, Trace ID, and Span ID. Trace-list output shows the root span’s start, duration, status, name, and Trace ID. trace view accepts a canonical Trace ID and shows a summary plus every span nested under the returned OTLP resourceSpans and scopeSpans. Use --json for the generated SDK’s complete success body, including OTLP attributes, events, links, resources, and scopes:

photon project telemetry trace list \
  --from 2026-08-24T01:00:00Z \
  --to 2026-08-24T02:00:00Z \
  --type delivery \
  --json

{"traces":[{"traceId":"0123456789abcdef0123456789abcdef","rootSpan":{"traceId":"0123456789abcdef0123456789abcdef","spanId":"0123456789abcdef","name":"GET /v1/calls","kind":2,"startTimeUnixNano":"1787533323004000000","endTimeUnixNano":"1787533323009000000","attributes":[],"events":[],"links":[],"status":{"code":1}}}]}

Restricted SQL

telemetry sql accepts only a JSON object containing sql and an optional string parameters map. The CLI preserves both values exactly after JSON decoding and does not expose --sql, --param, or similar flags that would put query values in shell history or the process list. Pass a regular file or pipe non-interactive stdin; an interactive terminal without --query-file exits with usage guidance.

{
  "sql": "SELECT trace_id, service_name FROM otel_traces WHERE endpoint = {endpoint:String} LIMIT 20",
  "parameters": {
    "endpoint": "/v1/calls"
  }
}

photon project telemetry sql --query-file ./query.json
printf '%s' "$PHOTON_OTEL_SQL_QUERY" |
  photon project telemetry sql --json

Photon’s API remains authoritative for read-only SQL validation, project row isolation, supported types, timeout, result size, and resource limits. The CLI does not rewrite a rejected statement, remove clauses, retry with a weaker query, or fall back to a direct database connection. SQL human output uses response column names and positional row order. SQL --json output is the complete generated SDK success response, not a smaller CLI DTO. With --debug, the route redacts its complete request and response bodies; normal stdout and JSON results are unchanged. Query text, parameters, and returned telemetry values are therefore not duplicated into HTTP diagnostics.

Get started

Projects

Account

Compliance

Reference

Developer telemetry

Logs and traces

Restricted SQL

​Logs and traces

​Restricted SQL

Logs and traces

Restricted SQL