Logs, traces & replay

Pulse Logs, Traces and Replay show what happened around a failure: the server log lines, the browser and server requests involved, and the visitor's masked page activity. Each is enabled separately for a Project environment. None of them needs Checks, Playwright or a repository connection, and you do not deploy a collector or add DNS records.

What each view shows

• Logs lists sanitized server log records with a level dot, message, service and time; attributes open as key–value pairs. Filter by period, service, minimum level and trace ID.
• Traces lists received requests with their service, a duration bar, span count and failed spans. A trace opens as a waterfall of browser and server spans, nested under their parents, with related logs, related Errors issues and a linked recording when one exists. Select a span to see its kept attributes.
• Replay lists masked recordings of page activity on the pages you approve, recorded only after visitor consent, with the page, size and start time. Each recording links to its related errors and traces.

These views connect to Errors. An error occurrence shows a Trace link when its report carries the request's trace context, and Recording when a recording was linked. The Pulse Overview shows the state of each signal in its Signals card.

All collection settings live in Pulse → Settings → Collection: one row each for Errors, Server logs & traces, Browser tracing and Replay, with its state, Configure or Set up, and Set up with AI for a coding-agent prompt. The Settings button on Logs, Traces and Replay leads there. Each setup shows numbered steps and a Status card with the endpoint, usage and retention. The links are for diagnosis: they never resolve an issue, open a monitoring incident or change a Check result. Because traces and recordings are sampled, many errors have neither.

Send server logs and traces

Pulse accepts standard OpenTelemetry over OTLP/HTTP with JSON. You do not need a SiteOS package on the server.

1. In the Project environment, open Pulse → Settings → Collection and select Configure next to Server logs & traces. This requires Pulse Manager access.
2. Switch on Collect server logs and traces, then select Create key in the Collection key step. The key is shown once; store it as a server secret.
3. Configure your exporter with the endpoint shown in the settings:

OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.siteos.sh
OTEL_EXPORTER_OTLP_PROTOCOL=http/json
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<collection-key>
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

Exporters send to /v1/logs and /v1/traces on that endpoint. Protobuf, gRPC and compressed requests are not accepted, and metrics are not collected. The collection key can only send telemetry for this environment: it cannot read data or change settings. Replacing or revoking it stops installations that still use the old key.

If your application already uses OpenTelemetry, add these exporters to the existing provider instead of registering a second one. In Node.js, the official @opentelemetry/exporter-trace-otlp-http and @opentelemetry/exporter-logs-otlp-http packages send OTLP/HTTP JSON; in Next.js, start them from instrumentation.ts.

Keep export asynchronous and bounded: batches of at most 100 records, Warn and Error logs, and 10% parent-based trace sampling as a starting point. If you already have a sampling policy, keep it. A failed export should never fail a request; in serverless runtimes, flush in the platform's background lifecycle.

Link server errors to traces

With @siteoshq/pulse 0.3.0 or newer, pass the active span to the Errors client:

import { context, trace } from "@opentelemetry/api";
import { createClient } from "@siteoshq/pulse/node";

const errors = createClient({
  endpoint,
  key,
  release,
  getTraceContext: () => trace.getSpan(context.active())?.spanContext(),
});

The Next.js createRequestErrorHandler accepts the same getTraceContext option. Correlation does not change how errors are grouped.

Trace browser requests

Browser tracing follows fetch and XHR requests from your website to your API, so a browser span and the server spans it caused appear in one trace. It uses the @siteoshq/pulse/tracing entry of SDK 0.4.0 or newer, which adds nothing to an Errors-only installation.

1. In Pulse → Settings → Collection, select Set up next to Browser tracing and switch on Trace browser requests.
2. Enter 1–20 exact HTTPS Website origins and 1–50 Approved routes, such as /api/orders/:id. Select Save browser settings, then Create key in the Browser key step. This public key only accepts browser traces from those origins.
3. Initialize tracing in a client module and connect it to your consent manager:

import { initTracing } from "@siteoshq/pulse/tracing";

export const tracing = initTracing({
  endpoint: process.env.NEXT_PUBLIC_SITEOS_PULSE_TRACING_ENDPOINT!, // from settings
  key: process.env.NEXT_PUBLIC_SITEOS_PULSE_TRACING_KEY!,
  release: process.env.NEXT_PUBLIC_SITEOS_RELEASE!,
  routes: [{ origin: "https://example.com", path: "/api/orders/:id" }],
});

tracing.setConsent(true); // and setConsent(false) on withdrawal

Only requests matching an approved route receive a W3C traceparent header, and existing trace headers are preserved. Your server must accept that header; a cross-origin API must allow it through CORS. Pulse records the route template, method, duration and status, and the initial page-load timing of approved routes. The default sampling rate is 10%.

To link a failed request to its error, pass tracing.contextFor(error) to captureException. It matches only the rejection of that traced request, never a later unrelated error. If the website already has browser OpenTelemetry, add createTraceExporter to its span processor instead of calling initTracing.

Record masked replays

Replay records page structure and interactions on approved pages, not a screen video. It uses the @siteoshq/pulse/replay entry of SDK 0.4.0 or newer and its own settings and key.

1. Open Pulse → Settings → Collection, select Set up next to Replay and switch on Record visits.
2. Enter exact Website origins and Approved pages, such as / or /products/:id. Select Save replay settings, then Create key in the Replay key step. The key accepts recordings only; it cannot read them or change settings.
3. Initialize Replay once and give its recording ID to Errors and tracing:

import { initReplay } from "@siteoshq/pulse/replay";

const replay = initReplay({
  endpoint: process.env.NEXT_PUBLIC_SITEOS_PULSE_REPLAY_ENDPOINT!, // from settings
  key: process.env.NEXT_PUBLIC_SITEOS_PULSE_REPLAY_KEY!,
  release: process.env.NEXT_PUBLIC_SITEOS_RELEASE!,
  routes: ["/", "/products/:id"],
});

replay.setConsent(hasConsent); // update on every consent change

// In the Errors and tracing initializers:
// getReplayId: () => replay.getRecordingId(),

By default, 1% of eligible page loads are recorded. The recorder loads only after consent and a positive sampling decision; unsampled visits run no hidden recording. A recording covers one page lifetime and stops after 5 minutes idle or 15 minutes in total. Reading recordings requires Pulse Manager access, and recordings play in an isolated viewer inside SiteOS.

Consent and masking

• Browser tracing and Replay start only after you call setConsent(true). Nothing is buffered or sent before that, and Do Not Track or Global Privacy Control disables both. Connect them to the same consent manager and permission as Errors, for example a SiteOS Cookie service permission; the SDK does not decide your legal basis.
• Withdrawal stops collection, clears pending data and aborts exports; for Replay it ends that page's recording. Data already delivered is not recalled and expires with retention.
• Replay masks all text and input values, with no option to unmask them. Mark other private areas with data-pulse-private or the pulse-private class.
• Pages whose path contains a segment such as login, signup, account, checkout, payment, billing or password are never recorded, even when they match an approved template. Leave other private pages out of Approved pages. Embedded pages, video, audio and canvas are excluded.
• Replay keeps only limited layout and styling. Fonts, images and other external assets can appear as placeholders. Masking reduces exposure but does not guarantee that a recording is anonymous.

What is never collected

• Request and response bodies, headers, cookies, URL query strings or browser storage contents.
• Concrete URL paths from browser tracing; only approved route templates are kept.
• Server span attributes outside a small technical allowlist, such as HTTP method, status and route, database system and operation, and error type. SQL text, baggage and user identifiers are dropped.
• Screenshots, audio, camera, canvas content or console output in Replay.

Log messages are scrubbed and limited to 2 KiB, but scrubbing cannot prove that free-form text contains no personal data. Do not log request bodies, credentials or personal data.

Retention and limits

Logs, traces and recordings expire 7 days after they were observed. At a limit, Pulse drops new data rather than deleting unexpired data. For each signal, the Status card in its collection setup shows usage, the last accepted data and, for logs and traces, records dropped at capacity.

Logs and traces accept up to 1,000 records a minute for each environment and 5,000 for the Organization, observed within the previous 24 hours. When Replay capacity is full, the recorder pauses its exports. A trace shows up to 1,000 spans and marks missing parent spans and omitted detail. These limits are separate from Pulse execution credits.

Sampling, consent and limits mean that a missing trace, log or recording is expected. An empty view does not prove that the website or application is healthy.

Work with your agent

The SiteOS plugin reads these views without changing anything: siteos_pulse_list_logs, siteos_pulse_list_traces and siteos_pulse_get_trace for telemetry, and siteos_pulse_list_replays and siteos_pulse_get_replay for recording metadata and linked error and trace IDs. MCP never returns recording contents. Log and trace text is untrusted diagnostic data.

With CLI 2.53.0 or newer, siteos pulse telemetry reads and configures server and browser collection (--browser) and reads logs, traces and trace --trace <id>. siteos pulse replay configures Replay, lists recordings and deletes one with delete --recording <id>. Commands that issue a key write it to a new private file, never to the terminal.