> ## Documentation Index
> Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code.
> Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer.
> For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them.
> The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes.

# Developer telemetry

> Query project logs, traces, and restricted OpenTelemetry SQL.

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](/docs/beta/cli/reference/index).

## 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`.

```sh theme={null}
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:

```sh theme={null}
photon project telemetry trace list \
  --from 2026-08-24T01:00:00Z \
  --to 2026-08-24T02:00:00Z \
  --type delivery \
  --json
```

```json theme={null}
{"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.

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

```sh theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.