Reporting

import HeaderLabel from '@site/src/components/Docs/HeaderLabel'; import VersionLabel from '@site/src/components/Docs/VersionLabel';

By default, proto prints rich, human-readable output to your terminal. But proto is increasingly run by scripts, CI pipelines, and AI agents, so we also support machine-readable output formats, and the ability to export telemetry to observability backends.

Reporters

The global --reporter option (or the PROTO_REPORTER environment variable) controls the format that proto prints output in. Three formats are supported:

• text (default) - Human-readable output with colors and styling.
• json - A single JSON document, printed once the command has completed.
• ndjson - Newline-delimited JSON, where each line is a standalone JSON object, streamed as the command runs.

$ proto --reporter json outdated
# Or
$ PROTO_REPORTER=json proto outdated

Both json and ndjson produce machine-readable output. The difference is when it's emitted: json buffers everything and prints once at the end, while ndjson streams each event as it happens, which is better suited to long-running commands and streaming consumers. When a command fails while using ndjson, the error is also serialized as JSON, so consumers can parse it instead of choking on a stack trace.

:::info

The older --json global flag (and PROTO_JSON environment variable) is still supported, and is equivalent to --reporter json.

:::

AI agents and bots

proto automatically detects when it's being run by an AI agent or bot, and switches the default reporter to ndjson in that environment — no flag required. You can always override this by explicitly passing --reporter (or setting PROTO_REPORTER).

OpenTelemetry

proto can export OpenTelemetry (OTEL) traces, logs, and metrics over OTLP, for integration with observability backends like Grafana, Honeycomb, or Datadog.

This is opt-in, and enabled with the following global options (or environment variables):

• --otel (PROTO_OTEL) - Export traces and metrics over OTLP.
• --otel-logs (PROTO_OTEL_LOGS) - Also export log events as OTLP logs.
• --otel-service-name <name> (PROTO_OTEL_SERVICE_NAME) - The service name to report. If not provided, the standard OTEL_SERVICE_NAME environment variable is used. <VersionLabel version="0.59.0" />

The OTLP destination and transport are configured using the standard OTEL_EXPORTER_OTLP_* environment variables, like OTEL_EXPORTER_OTLP_ENDPOINT.

$ export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
$ proto --otel install node

Transports<VersionLabel version="0.59.0" />

OTLP payloads can be delivered over HTTP (http/protobuf) or gRPC (grpc). The transport is selected with the standard environment variables, where the per-signal variable takes precedence over the generic one:

• OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, OTEL_EXPORTER_OTLP_METRICS_PROTOCOL, OTEL_EXPORTER_OTLP_LOGS_PROTOCOL - The transport for an individual signal.
• OTEL_EXPORTER_OTLP_PROTOCOL - The transport for all signals. When not set, defaults to http/protobuf.

The same precedence applies to endpoints, using OTEL_EXPORTER_OTLP_ENDPOINT and the per-signal OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (and friends) variables. When an endpoint starts with https://, TLS is enabled, and the collector's certificate is verified against the operating system's trust store.

# OTLP over gRPC
$ export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
$ export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
$ proto --otel install node

:::caution

The HTTP transport and TLS support are currently considered experimental.

:::

Disabling signals<VersionLabel version="0.59.0" />

The standard environment variables can also force signals off, even when the options above have enabled them. OTEL_SDK_DISABLED=true disables all signals, while OTEL_TRACES_EXPORTER=none, OTEL_METRICS_EXPORTER=none, and OTEL_LOGS_EXPORTER=none disable an individual signal. These variables can only disable a signal, never enable one.

Metrics

When OTEL is enabled, proto records the following metrics. Names ending in .attempts are counters, while names ending in .duration are histograms measured in milliseconds.