# Observability

The most expensive turn in any change loop — whether the author is you or an AI agent — is the verification turn: *did the change actually work, across every process it touched?* This pillar is how NetScript answers it. The runtimes emit real OpenTelemetry spans, a single W3C `traceparent` groups a cross-process flow into one distributed trace, structured logs ride the same OTLP export, and both a dashboard and a **typed query port** read it all back — for you, or for an agent verifying its own change. Use this pillar when you need to add tracing, inspect runtime behavior, or connect package-level telemetry to the running system.

[Overview & Concepts   Telemetry model  Trace context and logging across services, workers, sagas, and orchestration.](https://rickylabs.github.io/netscript/netscript/explanation/observability/) [Quickstart   Turn on tracing  Run aspire start, trigger a job, and watch the runtime's automatic spans land in the dashboard — the lowest-effort path to a first trace.](https://rickylabs.github.io/netscript/netscript/observability/telemetry/) [How-To   Add OpenTelemetry  Wire OTel into a workspace.](https://rickylabs.github.io/netscript/netscript/observability/how-to/add-opentelemetry/) [API Reference   telemetry  Generated telemetry package symbols.](https://rickylabs.github.io/netscript/netscript/reference/telemetry/) [API Reference   logger  Generated logger package symbols.](https://rickylabs.github.io/netscript/netscript/reference/logger/)

## Where to go next

Telemetry in NetScript is built-in, not bolted-on — the fastest route is to see a trace first, then learn the model:

- **Emit and view a trace:** [Telemetry & logging](https://rickylabs.github.io/netscript/netscript/observability/telemetry/)

  is the capability hub — automatic worker spans, the `@netscript/telemetry` helpers, browser logs, and the dashboard views, with [Add OpenTelemetry](https://rickylabs.github.io/netscript/netscript/observability/how-to/add-opentelemetry/)

  as the task recipe.
- **Understand the model:** [Observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/)

  maps what is framework-real versus a scaffold stub, and how trace context propagates across process boundaries.
- **See where telemetry is collected:** [Orchestration with Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

  explains the dashboard and OTLP collector the AppHost provisions; trace context crosses service boundaries at the [services](https://rickylabs.github.io/netscript/netscript/services-sdk/services/) seam.
- **Read a trace back in code:** the [Telemetry & logging](https://rickylabs.github.io/netscript/netscript/observability/telemetry/)

  hub's *Close the loop* section covers the typed `TelemetryQueryPort` read side — how a test or an agent asserts a span landed instead of eyeballing the dashboard.
- **Look up exact symbols:** [telemetry](https://rickylabs.github.io/netscript/netscript/reference/telemetry/) and

[logger](https://rickylabs.github.io/netscript/netscript/reference/logger/) references, and the [telemetry convention](https://rickylabs.github.io/netscript/reference/telemetry/convention/) (span naming, SpanKind, the `netscript.*` attribute rules).

## Learn, do, look up

[Learn  Trace the request model  Follow one request through services, jobs, and streams in the core-concepts tour.](https://rickylabs.github.io/netscript/netscript/concepts/) [Do  Recipes  Task-oriented recipes for this area, one problem each.](https://rickylabs.github.io/netscript/netscript/observability/how-to/) [Look up  `@netscript/telemetry` reference  Generated API reference. Related units: `logger`.](https://rickylabs.github.io/netscript/netscript/reference/telemetry/) [Understand  Observability  The design rationale behind this pillar.](https://rickylabs.github.io/netscript/netscript/explanation/observability/)