Logs become valuable when they help an engineer answer a production question quickly. A large volume of unstructured messages rarely achieves that. The foundation of useful logging is a shared event model, consistent context, and explicit controls for sensitive data.
Structured logging does not mean wrapping an arbitrary sentence in JSON. It means emitting stable, machine-readable fields whose meaning is understood across services.
Design an event schema
A practical application event usually includes:
- timestamp and severity;
- service name, environment, and version;
- event name and outcome;
- trace and span identifiers;
- request or correlation identifier;
- safe business identifiers when genuinely needed;
- error type and a sanitized error message;
- schema version.
The trace_id must come from the active distributed trace. Generating a new value for every log line destroys correlation. When an incoming request has no valid trace context, the instrumentation layer should create the trace once and propagate it through downstream calls.
Event names should describe what happened—payment.authorization.failed is more useful than Something went wrong. Free-form text can remain as a human-readable message, but queries and alerts should depend on stable fields.
Keep sensitive data out
Logs are frequently copied, indexed, retained, and accessed by many operational tools. That makes them a poor place for credentials, access tokens, session cookies, full request bodies, payment data, or unnecessary personal information.
Use an allowlist of permitted fields rather than trying to redact every dangerous field after the fact. When identifiers are required for support or fraud analysis, prefer scoped references, hashing where appropriate, and retention aligned with the business purpose. Redaction should be tested like any other security control.
Control cardinality and cost
High-cardinality fields can make observability platforms slow and expensive. Not every value belongs in an indexed label. Trace IDs, user IDs, and raw URLs are often useful as searchable fields but dangerous as metric labels. Separate the log event model from the metric model.
Sampling also needs intent. Debug events may be sampled aggressively, while security-relevant audit events and rare errors may require complete capture. Rate limits should protect both the application and the logging pipeline during failure storms.
Connect logs, metrics, and traces
Logs explain individual events, metrics reveal trends, and traces show the path of a request. They work best together. OpenTelemetry context propagation can connect these signals without inventing a separate correlation mechanism for each service.
An alert should start from a symptom—such as elevated latency or error rate—and lead the operator to relevant traces and structured events. If engineers must manually reconstruct identifiers across three systems during an incident, the observability design is incomplete.
Treat the schema as a contract
Document required fields, validate them in tests, and evolve them with an explicit schema version. Provide shared libraries or middleware so every team does not solve context propagation and redaction independently.
Finally, test failure behavior. What happens when the collector is unavailable? Can logging block the request path? Is there buffering? What is dropped first? A logging system that causes an outage while reporting an outage has failed its primary responsibility.
Standardized logs are not about producing more data. They are about creating reliable evidence: safe enough to retain, consistent enough to query, and connected enough to shorten the path from symptom to cause.
Reference
The OpenTelemetry Logs Data Model defines stable log fields, severity semantics and trace-context correlation.