What is structured logging? Fields, event time, and queries

Use structured logging to record typed event fields, keep event time, normalize older records, and query errors by service.

Best practices
Illustration of a rail yard sorting records onto separate tracks

Checkout errors are rising, and searching for “connection refused” finds messages from several services. The useful questions are narrower. Which service emitted each record? Do the events share an error code? How long did each operation run before it failed?

Structured logging gives those answers their own fields. A person can read the message, and a query can group by service or filter on duration once the backend has parsed and mapped the fields. JSON is a common way to encode the event. A JSON object with only a free-text message still leaves the other details to be extracted.

Start with one event you can query

Consider this synthetic record after normalization. It represents one checkout failure.

{
  "time": "2026-08-25T08:55:01Z",
  "status": "error",
  "message": "database connection failed",
  "service": "order",
  "event": "checkout.failed",
  "error_code": "DB_CONNECT_ERROR",
  "duration_ms": 1200,
  "trace_id": "00000000000000000000000000000001"
}

The message explains the failure to a reader. The stable event and error_code values give queries something less likely to change when someone edits that message. duration_ms is a number. If a producer sends "1200" as a string, verify or convert it at ingestion before using a numeric filter such as duration_ms > 900. A schema needs to say what a field means, which type and unit it uses, and how the pipeline treats missing values. Leaving a duration missing preserves the distinction from a measured zero.

Separate when the event happened from when the collector saw it. If a worker buffers this record and ships it two minutes later, a query for the failure should still use the event time when that time is available and valid. Keep the collector observation time separately if you need to inspect ingestion lag. OpenTelemetry models these as Timestamp and ObservedTimestamp. OpenTelemetry Logs Data Model

Emit a structured record at the source

Pick an encoding your collector understands, then configure the logger to emit it. JSON works well for typed values and nested data. A key-value format such as Logfmt can suit simpler records. If you use different encodings in development and production, test both ingestion paths.

This small Go program uses the standard library in Go 1.21 or later. Save it as log.go and run go run log.go.

package main

import (
	"log/slog"
	"os"
)

func main() {
	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
	logger.Error("database connection failed",
		"service", "order",
		"event", "checkout.failed",
		"error_code", "DB_CONNECT_ERROR",
		"duration_ms", 1200,
	)
}

The JSON handler emits one record with time, level, and msg alongside the event fields. The timestamp comes from the run, and this standalone program has no active trace. To match the first record's schema, configure your ingestion mapping from level and msg to status and message, and normalize the severity value. Go slog documentation

Check the same boundary on infrastructure logs. PostgreSQL 15 and later can emit jsonlog through log_destination; it requires logging_collector, which takes effect at server start. Confirm the file path, rotation, and collector configuration before changing the output. PostgreSQL logging configuration

Normalize older formats while they are still in use

A service you cannot change may still emit a stable text format. Parse a few representative lines in a Guance Pipeline to extract fields such as event time and severity. Try a valid event, a missing field, and a malformed line. Keep enough of the original for diagnosis within your data policy, and make parse failures visible. A pipeline affects records that pass through it; existing stored records need a separate migration or a query that accounts for both formats.

Align the same fields and types for the services you plan to compare. Start with the ones you need to investigate together, and inspect both the stored types and the fields available to queries. An object or array that a viewer can expand might need extraction or mapping before you can aggregate one of its nested values. Use your log index rules to control where records go and how long they are kept. Guance log indexes

Query the normalized fields

The following DQL example assumes that the collector has set source=checkout, routed the normalized record to the default log index, and parsed time as the event timestamp.

L("default")::checkout:(count(*) AS error_events)
{ `status` = "error" AND `event` = "checkout.failed" }
[1787648100000:1787648400000] BY service

The window is August 25, 2026, from 08:55 to 09:00 UTC. Change the source, index, and window for your own data. If the synthetic record above is the only matching row, the expected count for order is one. A retry can emit several records and a request can fail without emitting this event, so the result is an error-log count. Use a request measurement with a defined denominator for a request error rate. Guance DQL reference

Use the Guance Logs Explorer to inspect the extracted fields and filter on the ones supported by your index. Clustering can group similar messages in the selected scope so you can choose examples to inspect. Use an explicit count when you need totals or a trend, and set up a monitor separately if you need an alert.

Keep the context that connects records

When the request has active tracing context, capture its actual trace ID and include the span ID when you need to identify a particular operation. An application request ID can remain useful on its own and does not stand in for the tracing identifier. In Guance trace details, the whole-trace log view uses trace_id by default. Fields such as service, env, and version help determine the log index. Both signals need to be collected, retained, and accessible.

Keep the message readable, record only context with a diagnostic purpose, and keep credentials and unnecessary personal data out of logs. Measure serialization, parsing, and storage against your own workload before broadening the schema. A useful first test is whether the same failure can be found by field, within the right event-time window, across the services you need to compare.

Logs, metrics, and traces · Structured logging with Go slog

Get a tailored plan

Contact us

Join the community

Scan with WeChat
to join the community

Try Guance

Start online and pay only for what you use.

Get started

Choose a Guance plan

Code hosting