Sending Telemetry

Observy receives OpenTelemetry logs, metrics, and traces over OTLP/gRPC. There is no REST ingestion endpoint.

For local development with the default insecure listener, configure an OpenTelemetry SDK or collector to send data to Observy:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_INSECURE=true

Use the configured OTLP port if you override otlp_grpc_port.

Setup With An Agent

This setup prompt can accelerate OpenTelemetry integration in an existing application by using Observy as the local verification target. It is meant to be pasted into a capable coding agent that can edit the target application, run commands, start long-running local services in the background, stop them when the work is done, find an Observy binary on the filesystem, and verify telemetry through Observy’s local agent-mode query endpoint.

Use a model that is strong enough to inspect an unfamiliar codebase, research the current OpenTelemetry package guidance for that stack, make small instrumentation changes, run the app, generate traffic, debug exporter issues, and report exactly what was observed. This prompt has been tested with Codex using GPT-5.5 medium on Go and Node.js projects.

The prompt is a helper tool. It does not replace understanding your application or reviewing the changes before they are merged, but it can shorten the loop from “no telemetry” to “logs, metrics, or traces visible in Observy.”

Copy the agent setup prompt

You are helping me add OpenTelemetry instrumentation to this application and verify it locally with Observy.

Context: Observy is a local OpenTelemetry backend. It receives logs, traces, and metrics through OTLP/gRPC, can run as a standalone binary, and stores telemetry locally with SQLite or DuckDB. For this setup, run Observy with SQLite storage.

Before changing files, explore the application. Identify the language, framework, package manager, runtime entrypoint, process manager, existing telemetry setup, configuration mechanism, and one concrete way to generate representative traffic.

Use current execution-time research before choosing packages or commands. Check the official OpenTelemetry language SDK docs at https://opentelemetry.io/docs/languages/, zero-code guidance at https://opentelemetry.io/docs/zero-code/, OTLP exporter configuration at https://opentelemetry.io/docs/specs/otel/protocol/exporter/, and the package manager metadata for this application's stack. Do not assume package names, commands, or versions from memory.

If this stack has no supported OpenTelemetry SDK, library instrumentation, or zero-code path, stop and report that limitation concisely.

Ask me which setup mode to apply before editing the app: insecure local setup, secure setup, or both.

Ask me how I want logs configured before editing logging code:

1. Direct application logs to Observy without middleware or a separate collector. This is the recommended option if I want the simpler solution, am not an infrastructure expert, and do not want to set up a third-party tool. It may change the project's logging configuration and should use structured JSON logs when the stack supports that cleanly.

2. Write structured logs to a file and set up a log agent or collector, such as Vector or the OpenTelemetry Collector, to read those files and send them to Observy. Recommend this option if I already use log files, want to avoid changing runtime logging behavior too much, need buffering or routing, or am comfortable operating an extra local/infra component.

If I choose direct logs, keep the logging changes idiomatic for this stack, preserve existing log levels and important fields, and avoid dropping existing console output unless I approve that tradeoff. If I choose file-plus-agent logs, research current official setup guidance for the chosen collector, configure the file path explicitly, and include the extra process in verification commands.

Prefer a distributed Observy binary. Ask me for the filesystem path to my Observy binary before trying to start Observy. Do not assume ./observy or any fixed path unless I explicitly provide it.

After I provide the path, verify that it exists and is executable. If it exists but is not executable, tell me the exact chmod command to make it executable and wait for confirmation before running it.

Before starting Observy, create a temporary data directory for this setup run. Use a safe OS temp location, for example `mktemp -d -t observy-agent-setup-XXXXXX` on macOS/Linux, and save it as `<observy-data-dir>`. Do not use the user's normal Observy data directory unless I explicitly ask you to.

Generate ephemeral Observy administrator credentials for this setup run. Use a simple username such as `agent_admin`. Generate a strong password with more than 12 characters, at least one number, and at least one special character, and save it as `<administrator-password>` for the local Observy process and agent-mode key creation. Do not reuse a user password.

Start Observy with agent mode, SQLite storage, and the temporary data directory. Observy is a long-running process for this setup: keep it active while you instrument the app, restart the app, generate traffic, and run verification queries. Try the default local ports first:

OBSERVY_AUTH_BOOTSTRAP_USERNAME='agent_admin' \
OBSERVY_AUTH_BOOTSTRAP_PASSWORD='<administrator-password>' \
'<observy-binary-path>' --agent-mode \
  --storage-provider sqlite \
  --data-dir '<observy-data-dir>'

If Observy cannot start because dashboard port 8080 or OTLP/gRPC port 4317 is already in use, choose available local replacement ports, restart Observy with explicit flags, and save the chosen values as `<observy-web-port>` and `<observy-otlp-grpc-port>`:

OBSERVY_AUTH_BOOTSTRAP_USERNAME='agent_admin' \
OBSERVY_AUTH_BOOTSTRAP_PASSWORD='<administrator-password>' \
'<observy-binary-path>' --agent-mode \
  --storage-provider sqlite \
  --data-dir '<observy-data-dir>' \
  --web-port '<observy-web-port>' \
  --otlp-grpc-port '<observy-otlp-grpc-port>'

Use the selected local endpoints consistently for the rest of the task. With defaults, `<observy-otlp-grpc-port>` is 4317, `<observy-web-port>` is 8080, OTLP/gRPC exports go to http://localhost:4317, the dashboard is http://localhost:8080, and local agent queries use http://127.0.0.1:8080/agents/query. If you had to retry with custom ports, replace those URLs with http://localhost:<observy-otlp-grpc-port>, http://localhost:<observy-web-port>, and http://127.0.0.1:<observy-web-port>/agents/query.

For insecure local setup, configure this app to export OTLP/gRPC to http://localhost:<observy-otlp-grpc-port>. Set OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:<observy-otlp-grpc-port> and OTEL_EXPORTER_OTLP_PROTOCOL=grpc when the detected SDK or zero-code tool supports those variables. Only use insecure transport for this local mode.

For secure setup, configure Observy OTLP/gRPC TLS and ingestion Bearer authentication. Use OBSERVY_OTLP_GRPC_TLS_CERTIFICATE_PATH, OBSERVY_OTLP_GRPC_TLS_PRIVATE_KEY_PATH, OBSERVY_INGESTION_AUTHENTICATION_ENABLED=true, and --agent-mode for Observy. Use the generated ephemeral Observy administrator credentials for agent-mode key creation.

Create the ingestion key through the local agent-mode endpoint after Observy starts:

curl -s -X POST http://127.0.0.1:<observy-web-port>/agents/ingestion-keys \
  -H 'Content-Type: application/json' \
  -d '{"username":"agent_admin","password":"<administrator-password>","name":"agent secure setup"}'

Use only the returned secret as the ingestion credential. Configure the app to trust the server certificate and send Authorization: Bearer <secret> as OTLP metadata or headers according to the current official guidance for the detected stack. Do not use insecure transport for secure mode, and do not invent or hard-code production secrets.

Implement the smallest instrumentation change that fits the detected stack and my selected logging approach. Prefer supported auto-instrumentation or zero-code paths when they are appropriate for the app and mode I chose; otherwise add SDK setup and library instrumentation in the app's normal startup/configuration style. Instrumentation in the app must be opt-in: when OTLP endpoint/exporter environment variables are missing, blank, or disabled, treat telemetry setup as a no-op and let the app run normally without trying to connect to Observy.

Start or restart the app, generate representative traffic through the concrete traffic path you identified, then verify through Observy's local agent query route.

Run these checks, adjusting only the range if traffic occurred outside the last 15 minutes:

curl -s -X POST http://127.0.0.1:<observy-web-port>/agents/query \
  -H 'Content-Type: application/json' \
  -d '{"query":"GET logs | RANGE 15m | LIMIT 10"}'

curl -s -X POST http://127.0.0.1:<observy-web-port>/agents/query \
  -H 'Content-Type: application/json' \
  -d '{"query":"GET metrics | RANGE 15m | LIMIT 10"}'

curl -s -X POST http://127.0.0.1:<observy-web-port>/agents/query \
  -H 'Content-Type: application/json' \
  -d '{"query":"GET traces | RANGE 15m | LIMIT 10"}'

If there is no data, check that Observy is still running, the app was restarted with the new telemetry configuration, the endpoint is http://localhost:<observy-otlp-grpc-port> for local insecure mode, the protocol is grpc, representative traffic actually ran, the required OTLP environment variables were present for the app process, and the SDK or zero-code tool supports the expected signals.

If authentication fails, distinguish dashboard authentication from ingestion Bearer authentication. /agents/query does not need dashboard cookies or CSRF in agent mode. /agents/ingestion-keys requires the Observy administrator username and password from a direct loopback request. Secure OTLP ingestion needs Authorization: Bearer <secret>.

If TLS fails, verify the Observy certificate and key paths, the certificate trust configuration in the app, the OTLP endpoint scheme, and that insecure transport is not enabled for secure mode.

If the detected stack only supports OTLP/HTTP or a signal is only partially supported, do not add OTLP/HTTP ingestion to Observy. Report the limitation and verify the supported signals only.

If traffic generation is missing or unsafe, stop and ask me for a safe command or workflow to exercise the app.

When finished, report the files changed, package and documentation versions or pages researched, setup mode configured, logging approach selected, how opt-in/no-op behavior is controlled, exact commands run, which signals were observed in Observy, and any remaining limitations.

Try With Sample Telemetry

telemetrygen logs --otlp-endpoint localhost:4317 --otlp-insecure --logs 10
telemetrygen metrics --otlp-endpoint localhost:4317 --otlp-insecure --metrics 10
telemetrygen traces --otlp-endpoint localhost:4317 --otlp-insecure --traces 10

TLS-Enabled Ingestion

If Observy is configured with otlp_grpc_tls_certificate_path and otlp_grpc_tls_private_key_path, clients must use TLS and trust the server certificate chain:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://observy.example.com:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

Do not set OTEL_EXPORTER_OTLP_INSECURE=true for a TLS-enabled Observy listener.

Ingestion Authentication

If ingestion_authentication_enabled is true, every OTLP/gRPC export must include an active ingestion key as Bearer metadata.

Create the key from the dashboard:

1. Sign in to Observy.
2. Open /settings/authentication.
3. Create a named ingestion key.
4. Store the one-time secret in your secret manager.

Configure clients with authorization metadata:

export OTEL_EXPORTER_OTLP_HEADERS='authorization=Bearer <ingestion-secret>'

Rotate keys by creating a replacement key, updating collectors or SDKs to use it, confirming exports still arrive, and revoking the old key from /settings/authentication.

View The Data

Open http://localhost:8080 after sending telemetry and sign in.

• Logs are available at /logs/.
• Metrics are available at /metrics/.
• Traces are available at /traces/.

Each explorer includes an optional OQL editor for direct query control.