Design queryable logs

A good log event answers a question without a text parser. Emit one final event for each important operation, and put its result, duration, and business context on that event.

Emit one event per operation

Do not log started, processing, and completed for routine work. Emit one final event, for example in a finally block. With captureTelemetry, one call records a log, a span, and metric points for the operation:

import { captureTelemetry } from "@squasher-ai/node";

await captureTelemetry({
  event_name: "checkout.completed",
  kind: "log",
  level: status >= 500 ? "error" : "info",
  message: "checkout completed",
  attributes: {
    "checkout.item_count": 3,
    "http.response.status_code": status,
    "squasher.operation": "checkout",
    "squasher.outcome": status >= 400 ? "failure" : "success",
  },
  measurements: [{ name: "checkout.duration_ms", value: durationMs, unit: "ms" }],
  trace: {
    trace_id: traceId,
    span_id: spanId,
    span_name: "checkout",
    span_kind: "server",
    status: status >= 500 ? "error" : "ok",
    duration_ms: durationMs,
  },
});

captureTelemetry is also in @squasher-ai/nextjs. The same fields work on the HTTP API.

Use stable field names

Field	Use it for
`event_name`	A stable name, such as `checkout.completed`
`squasher.operation`	A stable operation or route name
`squasher.outcome`	`success` or `failure`. SDK sampling reads it.
`http.route`	The route template, not the raw URL with IDs
`http.response.status_code`	The status code, as a number
`service.name`	The service that owns the work
`deployment.environment.name`	`production`, `staging`, or another environment

Group and chart by fields with few values, such as route, region, and release. Use fields with many values, such as user or order IDs, only to find one exact event.

Keep attribute types

Send numbers and booleans as numbers and booleans, not as strings. The log helper in @squasher-ai/edge turns nested objects into dotted keys:

import { log } from "@squasher-ai/edge";

log.info("cache lookup completed", { cache: { hit: true, age_ms: 42 }, result_count: 8 });

This stores cache.hit=true, cache.age_ms=42, and result_count=8. The helper replaces the values of keys such as password, token, secret, cookie, authorization, and api_key with [REDACTED]. It keeps at most 64 attributes, 4 levels, and 2,048 characters for each string.

Sample by outcome

Keep failures and slow operations, and sample routine success:

import { init } from "@squasher-ai/node";

init({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
  sampling: { successRate: 0.1, errorRate: 1, slowRate: 1, slowThresholdMs: 1000 },
});

The SDK counts an event as a failure when its level is warning, error, or fatal, when its trace status is error, or when squasher.outcome is failure.
Events with the same trace ID get the same decision for the same rate.
When the SDK samples out an event that has measurements, it still sends the metric points.
alwaysSampleReleases and alwaysSampleUserIds keep every event for those releases and users.
The SDK never samples out LLM generation events.

This is sampling of single events. To decide once for a full trace, use tail sampling.

Protect private data

Do not record credentials, session cookies, authorization headers, prompts, or payment data.
Record route templates instead of raw URLs with customer IDs.
Use beforeSend in init to remove or change fields before the SDK sends an event.

Check the quality of your logs

squasher observe quality --project <project-id> --service-name checkout-api

The report checks that events have a service, environment, release, outcome, and trace correlation, and it finds duplicate events and attribute type changes. The Telemetry Quality API returns the same report. In Squasher, select Logs in the sidebar and use the Patterns and Changes tabs to compare logs.

Get started

Guides

Design queryable logs

Emit one event per operation

Use stable field names

Keep attribute types

Sample by outcome

Protect private data

Check the quality of your logs

Next steps

Node.js SDK

HTTP API

​Emit one event per operation

​Use stable field names

​Keep attribute types

​Sample by outcome

​Protect private data

​Check the quality of your logs

​Next steps

Node.js SDK

HTTP API

Emit one event per operation

Use stable field names

Keep attribute types

Sample by outcome

Protect private data

Check the quality of your logs

Next steps