How to Enable Runtime Instrumentation

One-page operator guide for the runtime instrumentation feature. Sprint reference: SPRINT_20260429_015_FindingsLedger_runtime_documentation task FL-RUNTIME-DOC-007.

Runtime instrumentation is disabled by default on every deployment. Operators opt in.

Step 1 — Flip the toggle

In the Findings Ledger configuration (env vars or appsettings.*.json):

{
  "findings": {
    "ledger": {
      "runtime": {
        "enabled": true
      }
    }
  }
}

Equivalent env var: FINDINGS__LEDGER__RUNTIME__ENABLED=true.

Restart the Findings Ledger WebService. The findings.runtime_* Postgres tables already exist (auto-migrated on first run); no manual SQL is required.

Step 2 — Verify the endpoint is reachable

With the toggle on, a query for an unknown finding should return 404 NotFound (proves the route is wired and the auth scope is set up; distinguishes from a 503 if the service was misconfigured):

stellaops findings runtime traces list \
    --finding-id 00000000-0000-0000-0000-000000000000
# expected: HTTP 404, exit code 4 — "no aggregates for this finding"

If you get a 200 OK with [], your build is older than the runtime instrumentation set; upgrade the Findings Ledger WebService image.

If you get 503 or connection refused, check:

Step 3 — Configure agent ingest

Configure your eBPF / syscall / APM agent to POST traces to:

POST {ledger}/api/v1/findings/{findingId}/runtime/traces
Authorization: Bearer <token>
Content-Type: application/json
X-StellaOps-TenantId: <tenant>

Body shape: see API reference §1 or the SDK sample at docs/samples/findings-runtime-sdk/sample-trace.json.

The agent-side configuration depends on the agent — link to the agent docs (TBD; agent docs land in a separate sprint).

Step 4 — Verify data is flowing

After the agent has run for a few minutes:

# Score should be 0..100; computedAt should be recent.
stellaops findings runtime score get --finding-id <real-id>

# Aggregates should list the hottest vulnerable functions.
stellaops findings runtime traces list --finding-id <real-id> --sort-by hits

# Timeline should show 'trace_ingested' events bucketed by hour.
stellaops findings runtime timeline range --finding-id <real-id> --bucket-hours 1

Disabling

Setting findings:ledger:runtime:enabled = false and restarting the WebService stops ingest and surfaces all reads as 404. Existing data is preserved — re-enabling resumes ingestion against the existing rows.

See also