Send and verify events with Winston structured event analytics
Use Winston structured event analytics where your app knows the final result. Collect only the fields you need, then verify a test event before building charts.
- 1
Choose the outcome
Node.js workflow monitoring
- 2
Define the contract
operation, request_id or job_id, status, and release
- 3
Log the final result
Use Winston transports and formats for diagnostic logs; send only the final fields required for a defined Telemetry question.
- 4
Check the stored event
Exercise a known fixture, then inspect job_completed for one correctly typed terminal row.
Before you start
Before you start
- Winston and telemetry-sh initialized once in a server or worker process
- Stable operation names, correlation IDs, error categories, and releases
- A shutdown policy for both Winston transports and outstanding Telemetry requests
Delivery setup
Install and initialize server-side
Import telemetry-sh in server-only code and initialize it once with process.env.TELEMETRY_API_KEY. Keep ingestion credentials out of browser bundles, client-visible environment variables, source control, logs, and exception messages.
npm installation
npm install telemetry-sh- 1Create one reusable server-side client. Set its timeout and retry limit.
- 2Log an event when the operation succeeds, fails, retries, or times out.
- 3Send test events with known results and inspect the stored rows before enabling an alert.
Snippet
Start with one structured event
Add this shape where the workflow completes, fails, or retries. Then build the dashboard from real fields.
Winston structured event analytics event
import winston from "winston";
import telemetry from "telemetry-sh";
const logger = winston.createLogger({
format: winston.format.json(),
transports: [new winston.transports.Console()],
});
const startedAt = performance.now();
try {
const result = await processImport();
const outcome = {
operation: "customer_import",
job_id: jobId,
status: "success",
duration_ms: Math.round(performance.now() - startedAt),
item_count: result.itemCount,
release: process.env.APP_RELEASE,
};
logger.info("customer import completed", outcome);
await telemetry.log("job_completed", outcome);
return result;
} catch (error) {
const outcome = {
operation: "customer_import",
job_id: jobId,
status: "failed",
duration_ms: Math.round(performance.now() - startedAt),
error_type: classifyError(error),
release: process.env.APP_RELEASE,
};
logger.error("customer import failed", { ...outcome, error });
await telemetry.log("job_completed", outcome);
throw error;
}Event schema
operation, request_id or job_id, status, and release
duration_ms, error_type, retry_count, and item_count
service, environment, feature, and approved account context
Check your setup
Checkpoint 1
Use Winston transports and formats for diagnostic logs; send only the final fields required for a defined Telemetry question.
Checkpoint 2
Do not create a Winston transport that forwards arbitrary log records unless every message and metadata field has a reviewed schema and redaction policy.
Checkpoint 3
Test delivery rejection and shutdown behavior separately because completing one transport does not flush another network client.
Verification
Prove the event arrived
Run this after exercising known success and failure cases. Replace the fallback table name if your final event contract differs from the snippet.
Winston structured event analytics verification query
SELECT *
FROM job_completed
ORDER BY timestamp_utc DESC
LIMIT 20;Implementation references
Review the event contract, data-safety guidance, and upstream primary documentation before enabling a new production path.
Where to log
Keep the outcome event small and recoverable
This pattern provides
- Record the outcome as an event you can query with SQL.
- Stable fields for dashboards, alerts, and cross-event correlation.
- Test events for checking success, failure, retries, and timeouts.
This pattern does not provide
- An OTLP exporter, automatic collection pipeline, or replacement for detailed traces and diagnostic logs.
- Exactly-once delivery merely because the payload contains an event ID.
- Permission to collect raw provider payloads, user content, credentials, or regulated data.
Example event schemas
Event schemas for this workflow
Check what each event records, when to send it, and which field types it needs. Review the example payload and privacy checklist before using it in production.
Use these queries in Telemetry
Learn about Alerts
Add a threshold and recipients to your reliability query to get alerts.
Related SQL recipes
More SQL recipes
Run the query using this workflow's event fields and check the example result. Save the result to a dashboard or set up an alert.
Calculate API error rate by route
Which API routes have the highest 5xx error rate with at least 20 requests?
Open recipeCalculate p50, p95, and p99 API latency
Which endpoints have the worst tail latency?
Open recipeMeasure background job retry and failure rate
Which background jobs consume the most retries or still fail?
Open recipeRank error fingerprints by customer impact
Which error groups affect the most customer accounts?
Open recipeMeasure Telemetry volume by event name
Which event contracts create the most ingestion volume?
Open recipeBrowse by implementation family
Compare related integration patterns
Templates to pair with this integration
API error and latency monitor
Watch request volume, status codes, route latency, failed endpoints, and customer-impacting API incidents.
Open templateBackground job failure monitor
Capture queue, cron, import, billing sync, and webhook job health from the first run through retries and failures.
Open templateEvent tracking plan template
Document what each event means, who owns it, which fields it contains, and which queries depend on it. Include privacy, retention, and validation rules.
Open templateMore integrations
Node.js and Express structured logging
Instrument Express route outcomes with stable route templates, status codes, request latency, and safe correlation fields.
Open guidePython and FastAPI structured logging
Capture FastAPI request outcomes and latency with the asynchronous Telemetry client and normalized route names.
Open guidePino structured event analytics
Keep Pino diagnostic logs and send selected completion events to Telemetry to analyze Node.js requests, jobs, and product reliability.
Open guide