Reporting

v0.58.0

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. v0.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

Transportsv0.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 signalsv0.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.

Operation	Metrics	Attributes
Tool install	proto.tool.install.attempts, proto.tool.install.duration	tool, strategy, status, cache
Tool install step	proto.tool.install.step.attempts, proto.tool.install.step.duration	tool, step, status
Tool uninstall	proto.tool.uninstall.attempts, proto.tool.uninstall.duration	tool, scope, status, cache
Plugin load	proto.plugin.load.duration	plugin, locator, status, cache
Plugin create	proto.plugin.create.duration	plugin, locator, status