Tool
watch
Collect a running program’s telemetry and resource use so you can investigate it with SQL.
watch starts a process with its OpenTelemetry export settings pointed at RepoQL’s local collector. Traces, logs, and metrics that the application emits become queryable data. RepoQL also samples process CPU and memory use.
Know what the application can tell you
A trace describes an operation through timed spans, such as a request and the database calls it makes. Logs record events; metrics record measurements over time. The application’s instrumentation determines which of these signals exist and what they mean.
Starting a process under watch does not add tracing to its methods. An application needs OpenTelemetry support and export enabled to send those signals. CPU and memory samples can still be available without an application SDK; very short processes may finish before useful samples are collected.
Keep the run identity with the evidence
The MCP call returns once the process starts and the telemetry store exists, allowing the agent to query it while it runs. The response includes the run identifier, process identifier, and query information. CLI watch also prints run details and stays attached to the process.
Runs share the watch SQL schema and are distinguished by run_id. Preserve that identifier when comparing runs, so another process’s activity does not become part of your measurement.
Start with a summary
Terminal
rql query "SELECT * FROM watch.summary()"The summary distinguishes captured payloads from decoded spans, logs, and metrics. An empty span table can mean the application has no tracing, exports elsewhere, or has not sent a batch yet. It does not by itself prove the process failed.
Use Profiling with watch for a workflow that checks capture, finds slow operations, and compares a change.
Parameters and query reference
| MCP parameter | Use |
|---|---|
| executable | Required. Program name or path. |
| arguments | Optional. Argument array, passed directly to the program. |
| workingDirectory | Optional. Working directory; otherwise the caller’s directory is used. |
| environment | Optional. Additional variables as key=value;key2=value2. |
The child inherits the environment, then caller overrides, then RepoQL’s collector wiring. RepoQL replaces exporter endpoints and related capture settings. It preserves an explicit service name and appends its routing information to headers and resource attributes.
Terminal
rql query 'SELECT object, kind, "what it answers"
FROM watch.surface ORDER BY object'| Query surface | Use |
|---|---|
| watch.summary() | Run status, captured signals, and next-query hints. |
| watch.errors() | Grouped failures. |
| watch.span_stats() | Operation timing statistics. |
| watch.available_metrics() | Metric names, units, and query hints. |
| watch.surface | The installed query surface, with examples and return columns. |
Telemetry is stored locally under the host repository’s .repoql/cache/otel/. Completed and stale inactive runs older than six hours are eligible for cleanup. Export evidence you need to keep. These profiling records are separate from RepoQL usage telemetry.
Further reference
In the installed manual: help:///tools/watch/watch.md, help:///commands/watch.md.