Português | English
Axio is a structured logger for Go, focused on observability, audit, and data governance. It standardizes fields, reduces the risk of sensitive data leakage, and enables correlation with distributed tracing, without coupling your application to the internal logging engine.
Direct dependency on logging libraries (Zap, Logrus, zerolog) couples the entire application to a specific implementation. Changes to the logging engine require refactoring dozens of files.
Axio functions as an abstraction layer with a stable interface (Logger). Business code depends only on the Axio interface, not on the internal engine.
| Advantage | Description |
|---|---|
| Decoupling | Business code doesn't know about Zap |
| Facilitated migration | Change internal engine without refactoring apps |
| Consistency | Same API for all teams/services |
| Extensibility | Hooks, metrics, tracing via composition |
| Testability | Interface facilitates mocks in tests |
| Centralized governance | PII, audit, formats in one place |
┌─────────────────────────────────────────────────┝
│ Application (business code) │
│ ↓ │
│ axio.Logger (interface) │
│ ↓ │
│ ┌─────────────────────────────────────────┝ │
│ │ Axio Core │ │
│ │ ┌─────┝ ┌─────┝ ┌───────┝ ┌─────────┝ │ │
│ │ │ PII │ │Audit│ │Tracing│ │ Metrics │ │ │
│ │ └─────┘ └─────┘ └───────┘ └─────────┘ │ │
│ │ ↓ │ │
│ │ Logging Engine │ │
│ │ (Zap - replaceable) │ │
│ └─────────────────────────────────────────┘ │
│ ↓ │
│ Outputs (Console/File/Stdout) │
└─────────────────────────────────────────────────┘
- Installation
- Quick Example
- Configuration
- Features
- Command Line: axio render and axio verify
- Logging Best Practices
- Guide by Service Type
- Examples and Anti-patterns
- Troubleshooting
Requires Go 1.27 or newer.
go get github.com/pragmabits/axioimport "github.com/pragmabits/axio"Complete HTTP handler with context, annotations, and cleanup:
package main
import (
"log"
"net/http"
"time"
"github.com/pragmabits/axio"
)
var logger axio.Logger
func main() {
var err error
logger, err = axio.New(axio.Config{
ServiceName: "sales-api",
ServiceVersion: "1.0.0",
Environment: axio.EnvironmentProduction,
Level: axio.LevelInfo,
})
if err != nil {
log.Fatal(err)
}
defer logger.Close()
http.HandleFunc("/api/orders", handleOrder)
http.ListenAndServe(":8080", nil)
}
func handleOrder(w http.ResponseWriter, r *http.Request) {
start := time.Now()
ctx := r.Context()
// ... business logic ...
logger.Info(ctx, "order created",
axio.Field("http", axio.HTTP{
Method: r.Method,
URL: r.URL.Path,
StatusCode: 201,
LatencyMS: time.Since(start).Milliseconds(),
ClientIP: r.RemoteAddr,
}),
axio.Field("user_id", "usr_123"),
)
w.WriteHeader(http.StatusCreated)
}| Field | Type | Required | Default | Values | Validation |
|---|---|---|---|---|---|
ServiceName |
string |
No | "" |
any | - |
ServiceVersion |
string |
No | "" |
any | - |
Environment |
Environment |
No | development |
production, staging, development |
ErrInvalidEnvironment if invalid |
InstanceID |
string |
No | "" |
any | - |
Level |
Level |
No | info |
debug, info, warn, error |
ErrInvalidLevel if invalid |
CallerSkip |
int |
No | 0 |
>= 0 |
- |
OmitCaller |
bool |
No | false |
true, false |
- |
AgentMode |
bool |
No | false |
true, false |
If true, outputs must be stdout+json |
Outputs |
[]OutputConfig |
No | auto | see OutputConfig | Validated individually |
PIIDisabled |
bool |
No | false (masking on) |
true, false |
- |
PIIPatterns |
[]PIIPattern |
No | [cpf, cnpj, credit_card] |
see PII table | - |
PIIFields |
[]string |
No | DefaultSensitiveFields() |
any | - |
PIIMaxDepth |
int |
No | 0 (= 32) |
>= 0 |
ErrInvalidPIIMaxDepth if negative |
PIIOmitErrorVerbose |
bool |
No | false |
true, false |
- |
PIIIdentifierShapes |
[]string |
No | [] |
RE2 shapes, see PII | ErrBroadPIIIdentifierShape if broad |
PIICustomPatterns |
[]CustomPII |
No | [] |
see CustomPII | Regex must be valid |
TracerType |
string |
No | noop |
otel, noop |
ErrInvalidTracer if invalid |
Audit |
AuditConfig |
No | disabled | see AuditConfig | - |
Metrics |
MetricsConfig |
No | disabled | see MetricsConfig | - |
| Field | Type | Required | Default | Values | Validation |
|---|---|---|---|---|---|
Type |
OutputType |
Yes | - | console, stdout, file |
ErrInvalidOutputType if invalid |
Format |
Format |
Yes | - | json, text |
ErrInvalidFormat if invalid |
Path |
string |
Conditional | "" |
file path | ErrFileOutputNoPath if Type=file and empty |
Rotation |
RotationConfig |
No | disabled | see RotationConfig | Only used when Type=file |
| Field | Type | Required | Default | Values | Validation |
|---|---|---|---|---|---|
MaxSize |
int |
No | 0 |
megabytes (0 = no size limit) | - |
MaxAge |
int |
No | 0 |
days (0 = no age limit) | - |
MaxBackups |
int |
No | 0 |
count (0 = retain all) | - |
Compress |
bool |
No | false |
true, false |
- |
LocalTime |
bool |
No | false |
true, false |
- |
Interval |
Duration |
No | 0 |
e.g., 24h, 1h30m, 500ms |
- |
| Field | Type | Required | Default | Values | Validation |
|---|---|---|---|---|---|
Enabled |
bool |
No | false |
true, false |
- |
StorePath |
string |
Conditional | "" |
file path | ErrAuditWithoutPath if Enabled=true and empty |
| Field | Type | Required | Default | Values | Validation |
|---|---|---|---|---|---|
Enabled |
bool |
No | false |
true, false |
- |
MeterName |
string |
No | axio |
any | - |
MeterVersion |
string |
No | 1.0.0 |
any | - |
Axio supports configuration via YAML, JSON, or TOML:
// Load from file (detects format by extension)
config, err := axio.LoadConfig("/etc/axio/config.yaml")
// Load from io.Reader (specify format)
config, err := axio.LoadConfigFrom(reader, "yaml")
// Panic version (useful in main)
config := axio.MustLoadConfig("/etc/axio/config.yaml")Complete YAML example:
serviceName: sales-api
serviceVersion: 2.1.0
environment: production
instanceId: pod-abc123
level: info
callerSkip: 0
omitCaller: false
agentMode: false
outputs:
- type: stdout
format: json
- type: file
format: json
path: /var/log/app.log
rotation:
maxSize: 100
maxAge: 30
maxBackups: 10
compress: true
interval: 24h
piiDisabled: false
piiPatterns:
- cpf
- cnpj
- email
- credit_card
piiFields:
- password
- token
- secret
piiMaxDepth: 8
piiOmitErrorVerbose: false
piiIdentifierShapes:
- "\\d{14,23}-[0-9a-f]{64}\\.csv"
piiCustomPatterns:
- name: employee_id
pattern: "EMP-\\d{6}"
mask: "EMP-******"
audit:
enabled: true
storePath: /var/lib/axio/chain.json
tracer: otel
metrics:
enabled: true
meterName: axio
meterVersion: 1.0.0| Type | Destination | Typical use |
|---|---|---|
console |
stderr | Local development |
stdout |
stdout | Containers with collection agents |
file |
file | Environments without agents, auditing |
| Format | Description | Use |
|---|---|---|
json |
Structured JSON | Production, aggregation systems |
text |
Colored text | Local development |
| Environment | Default Output | Format | Stack Trace |
|---|---|---|---|
development |
Console | Text | No |
staging |
Stdout | JSON | On errors |
production |
Stdout | JSON | On errors |
// Multiple outputs
logger, _ := axio.New(config,
axio.WithOutputs(
axio.Console(axio.FormatText),
axio.Stdout(axio.FormatJSON),
axio.MustFile("/var/log/app.log", axio.FormatJSON),
),
)
// Agent mode (stdout + JSON, optimized for Promtail, Fluent Bit, etc.)
logger, _ := axio.New(config, axio.WithAgentMode())Options override the config file: the first WithOutputs replaces the file's outputs, which are then neither opened nor validated, and later calls add to it.
File outputs support automatic rotation by size, time interval, or both:
// Size-based rotation (rotate when file exceeds 100 MB)
out, _ := axio.RotatingFile("/var/log/app.log", axio.FormatJSON, axio.RotationConfig{
MaxSize: 100,
MaxBackups: 5,
Compress: true,
})
// Time-based rotation (rotate every 24 hours)
out, _ := axio.RotatingFile("/var/log/app.log", axio.FormatJSON, axio.RotationConfig{
Interval: axio.Duration(24 * time.Hour),
MaxAge: 30,
})
// Combined (whichever triggers first)
out, _ := axio.RotatingFile("/var/log/app.log", axio.FormatJSON, axio.RotationConfig{
MaxSize: 100,
Interval: axio.Duration(24 * time.Hour),
MaxBackups: 10,
MaxAge: 30,
Compress: true,
})
logger, _ := axio.New(config, axio.WithOutputs(out))
defer logger.Close()Every output on one file shares the process's one rotator for it, so any number of loggers can write to the same path, each through its own RotatingFile or the same OutputConfig. An Output value, though, belongs to the one Logger it is given to, and giving it to a second fails with ErrOutputInUse. The same path opened with another rotation, or as a plain File, fails with ErrRotationConflict. While any output has the file open, the process holds a lock on the file beside it (app.log.lock), and another process opening the same rotating file fails in New with ErrRotatingFileLocked. The lock uses flock, so Windows, Solaris and AIX have none.
A file rotates on the write that would take it past MaxSize, or on the first write once Interval has passed since its last rotation, by size or by time. The time of the last rotation is the lock file's modification time, so a restart does not start the interval again, and a file nothing was written to is not rotated. A write larger than MaxSize goes whole into the file. A rotation that fails keeps the line in the current file, is reported on stderr and by LastRotationError (RotationErrorReporter), and is tried again after another interval or another MaxSize. Backups are named as lumberjack names them, app-2006-01-02T15-04-05.000.log, and after each rotation the oldest are removed by MaxBackups and MaxAge and the rest compressed when Compress is set, in the background: Close does not wait for it.
MustRotatingFile is available for initialization where failure should be fatal.
| Level | Constant | Semantics | When to use |
|---|---|---|---|
| Debug | LevelDebug |
Technical details | Development, troubleshooting |
| Info | LevelInfo |
Normal events | Start/end of operations, milestones |
| Warn | LevelWarn |
Non-critical anomalies | Timeouts, fallbacks, degradation |
| Error | LevelError |
Real failures | Operation failed, requires attention |
Methods:
logger.Debug(ctx, "debug details")
logger.Info(ctx, "items processed", axio.Field("count", count))
logger.Warn(ctx, err, "timeout querying supplier")
logger.Error(ctx, err, "failed to persist order")The message is written as given, never formatted. Data goes in annotations passed after it, which the entry carries after those of the logger (With) and which no other call sees.
Adds key-value fields to the log:
logger.Info(ctx, "order created",
axio.Field("user_id", "usr_123"),
axio.Field("order_id", "ord_456"),
axio.Field("amount_cents", 15000),
)An annotation named like a key axio writes itself — timestamp, level, message, logger, caller, stacktrace, service, deployment, trace_id, span_id, error (with errorVerbose and errorCauses), event, duration_ms, previous_hash, hash — is written behind an underscore, as _message, so a line never carries the same key twice.
A struct, a map, or a slice zap has no encoder of its own for is written as its JSON encoding, in encoding/json/v2: nil slices and maps as null, map keys in sorted order, a time.Duration as its nanoseconds and a byte array as base64. A slice of a basic type given as the annotation's own value — []string, []int, []bool, []time.Duration, []time.Time, []error and the like — is written by zap instead: a nil one as [], and durations in milliseconds, as a time.Duration annotation is. omitempty omits a field whose value encodes as empty — "", null, [], {} — and omitzero omits false, 0 and every other zero value. A tag option the encoding does not accept, such as ,string on a slice, makes the value fail: the line carries <key>Error in its place.
Returns a logger that attaches its annotations to every entry it writes, before those each call passes. Use it for fields that hold across several lines, such as a request's ID; the fields of one line go in the call itself:
requestLogger := logger.With(axio.Field("request_id", requestID))
requestLogger.Info(ctx, "order created", axio.Field("user_id", userID))
requestLogger.Error(ctx, err, "payment failed")Struct for HTTP request metadata:
logger.Info(ctx, "request processed", axio.Field("http", axio.HTTP{
Method: "POST",
URL: "/api/v1/orders",
StatusCode: 201,
LatencyMS: 45,
UserAgent: r.UserAgent(),
ClientIP: r.RemoteAddr,
}))| Field | Type | Description |
|---|---|---|
Method |
string |
HTTP method (GET, POST, etc.) |
URL |
string |
Request path |
StatusCode |
int |
Response code |
LatencyMS |
int64 |
Latency in milliseconds |
UserAgent |
string |
Client User-Agent |
ClientIP |
string |
Client IP |
Implement Annotable for types that produce multiple fields:
type Order struct {
ID string
Items []Item
secret string // will not be logged
}
func (o Order) Append(target []axio.Annotation) []axio.Annotation {
return append(target,
axio.Field("order_id", o.ID),
axio.Field("item_count", len(o.Items)),
)
}
// Usage — fields are expanded individually in the log output
logger.Info(ctx, "order processed", axio.Field("order", order))The fields are expanded before any hook runs, so PII masking and custom hooks see each one.
Creates loggers with namespace:
httpLogger := logger.Named("http")
dbLogger := logger.Named("db")
cacheLogger := logger.Named("cache")
httpLogger.Info(ctx, "request received") // logger: "http"
dbLogger.Info(ctx, "query executed") // logger: "db"Hooks process log entries before writing. Executed in fixed order:
- PIIHook - the one every logger runs unless
WithPIIDisabledorpiiDisabledturns it off, which masks sensitive data - Custom hooks - in the order passed to
WithHooks
A PIIHook passed to WithHooks is one of the custom hooks and runs where it was passed: with WithPIIDisabled, that masks what an earlier custom hook adds. With the default masking on, every custom hook sees the masked entry.
Auditing is not a hook: the hash is computed when the entry is written, after every hook, so it covers whatever the hooks changed.
A hook changes what is written through the Message, Error, TraceID, SpanID and Annotations of the *Entry it receives. Timestamp, Level, Logger and Caller are read only, and Caller comes in the form the line writes: checkout/handler.go:42.
type Hook interface {
Name() string
Process(ctx context.Context, entry *Entry) error
}type TenantHook struct {
tenantID string
}
func (h TenantHook) Name() string { return "tenant" }
func (h TenantHook) Process(ctx context.Context, entry *axio.Entry) error {
entry.Annotations = append(entry.Annotations,
axio.Field("tenant_id", h.tenantID))
return nil
}
// Usage
logger, _ := axio.New(config, axio.WithHooks(TenantHook{tenantID: "acme"}))PII (Personally Identifiable Information) is any data that can identify a person, directly or indirectly. Examples: CPF, CNPJ, email, phone, IP address, card numbers.
In environments with centralized logs, exposed PII represents risk of:
- Data leakage
- Non-compliance with LGPD/GDPR
- Exposure in security incidents
References:
| Pattern | Constant | Detected formats | Mask |
|---|---|---|---|
| CPF | PatternCPF |
123.456.789-01, 12345678901 |
***.***.***-** |
| CNPJ | PatternCNPJ |
12.345.678/0001-90 |
**.***.***/****-** |
| Credit Card | PatternCreditCard |
1234-5678-9012-3456 |
****-****-****-**** |
PatternEmail |
user@domain.com |
***@***.*** |
|
| Phone | PatternPhone |
(11) 99999-9999, +5511999999999 |
(**) *****-**** |
| Phone (no area) | PatternPhoneNoDDD |
99999-9999 |
*****-**** |
A number glued to a label is still masked: cpf12345678901 becomes cpf***.***.***-**. Digits glued to more digits, as in a 13-digit timestamp, or inside a hex identifier — a run of hex digits with a letter among them, such as a trace id or a hash — are not taken for PII, so a label made only of hex letters, as in cafe12345678901, leaves its number unmasked.
A UUID is not PII: the built-in patterns never match inside a whole UUID — 32 hex digits in groups of 8-4-4-4-12 carrying the RFC 9562 version and variant, or the nil UUID, with no hex digit on either side — so an identifier is never masked as a card or a phone number. PII glued to a UUID is still masked, and custom patterns read the text as it is.
A file name carrying a timestamp has the shape of a number: 20261107041818.csv is masked as a CNPJ. Declare the shape of such an identifier, in RE2, with axio.WithPIIIdentifierShapes(...), piiIdentifierShapes in the config file, or PIIConfig.IdentifierShapes, and the built-in patterns for a number — CPF, CNPJ, card, phone — never match inside it, as inside a UUID. A number that crosses its border, or one elsewhere in the same text, is still masked, and the e-mail and custom patterns read the text as it is. A match that starts or ends inside a word is no identifier, so \d{14}\.csv leaves cnpj12345678000195.csv masked; a prefix glued to the number goes into the shape, as in relatorio_\d{14}\.xlsx.
logger, err := axio.New(config,
axio.WithPIIIdentifierShapes(`\d{14,23}-[0-9a-f]{64}\.csv`),
)A shape holds the context around its number, inside one word: every text it matches holds an ASCII letter written as is (under (?i) a k or s does not count: it also matches the Kelvin sign or the long s), no whitespace is written in it, and every class in it, . included, matches only ASCII letters, digits and _ ((?i)[a-z] included) — only hex digits when it matches a digit. New refuses one that does not, such as \d{14}, .*, \d{14}.*\.csv or \d{11} reais, with ErrBroadPIIIdentifierShape. Whatever a shape matches is never masked as a number, so a shape that names PII, such as cpf\d{11}, leaves it in the clear, and a hex class takes in a number glued to the identifier by a separator, as id_[0-9a-f]+(?:-[0-9a-f]+)* takes in the CPF of id_ab-12345678901. A shape is searched for only in a text where a pattern for a number already matched: a line with no such number pays nothing for it, and one holding the identifier about 1 µs and two allocations more.
Fields whose names contain these terms are automatically redacted to [REDACTED]:
password, senha, token, api_key, apikey, secret, credential, authorization, bearer, private_key, privatekey, access_key, secret_key, client_secret, clientsecret
Every Logger and Event masks by default, with the CPF, CNPJ and credit card patterns and the sensitive fields above, whether its Config comes from DefaultConfig, from a literal or from a file. Masking scans every entry: a line costs roughly 2× as much for a plain message, 2 to 3× with strings, a map or an error, and up to about 4.5× for a struct or an HTTP annotation. A service that logs no personal data can turn it off.
// On by default
logger, _ := axio.New(config)
// Other patterns or fields; the patterns listed replace the default ones
logger, _ := axio.New(config,
axio.WithPII(
[]axio.PIIPattern{axio.PatternCPF, axio.PatternEmail},
axio.DefaultSensitiveFields(),
),
)
// Off
logger, _ := axio.New(config, axio.WithPIIDisabled())
// As a custom hook, masking what an earlier hook adds
hook := axio.MustPIIHook(axio.DefaultPIIConfig())
logger, _ := axio.New(config, axio.WithPIIDisabled(), axio.WithHooks(enricher, hook))
// Via Config (YAML file)
// piiPatterns: [cpf, cnpj, email]
// piiDisabled: true # turns masking offconfig := axio.PIIConfig{
Patterns: []axio.PIIPattern{axio.PatternCPF},
CustomPatterns: []axio.CustomPII{
{
Name: "employee_id",
Pattern: `EMP-\d{6}`,
Mask: "EMP-******",
},
},
Fields: axio.DefaultSensitiveFields(),
}PII masking covers every value the caller hands a line — the message, the error and every annotation:
- The message.
- The error passed to
Warn,ErrororEvent.SetError, by its message and, for an error that formats itself, its verbose form (errorVerbose). A masked error still unwraps to the original, soerrors.Iskeeps working in later hooks. - Annotation names matching
PIIConfig.Fields— the whole value becomes[REDACTED], whatever its type. - Strings, errors and
fmt.Stringervalues, by their text. - Bytes — a
[]byte, a byte array or a named byte-slice type, which are written as base64 — by the text they hold: masked text stays bytes, and bytes that are not UTF-8 text cannot be inspected and become[REDACTED], whether an annotation of their own or a field or element of a structured value. A byte array or a named byte-slice type is looked for only in a structured value whose type may hold one, or holds an interface: encoding such a value costs one more allocation per field or element, and any other type pays nothing. - Base64 text. Any string with the shape of base64, in the standard or the URL alphabet, padded or not — the message, the error, an annotation, a value inside a map or struct — is also decoded, and masked when the text it decodes to carries PII. That is how bytes of text inside a structured value arrive, its JSON encoding carrying them as base64. A string that decodes to binary data becomes
[REDACTED]when a pattern matches inside it, and passes as it is otherwise: nothing tells the base64 of other binary data from any other string of that shape. - JWTs and JWEs. A token anywhere in a text — a message, a URL query, an annotation — becomes
[REDACTED]whole: it is a credential, and its claims may carry what no pattern knows. A string is taken for a token when it has a token's shape and its header decodes to a JSON object naming an algorithm (alg), as every JOSE header does. A JWS or JWE in JSON serialization — an object with apayloadand itssignatureorsignatures, or with aciphertextand itsiv— becomes[REDACTED]whole inside a structured value; written as text in a message, it passes. - Encoding failures. A value whose encoding fails — a
MarshalJSON,MarshalLogObjectorMarshalLogArraythat returns an error — has that error masked where it is written, under<key>Error, and the part it did write masked like any value. - Structured values — maps, slices, structs, pointers,
http.Header— walked as the JSON encoding the log writes for them: at every level, keys are checked againstFieldsand strings against the patterns. Annotablevalues such asHTTP, expanded into their fields before any hook runs.
What axio writes itself — the logger name, the service metadata, the caller and the stack trace — is written as it is, never scanned.
A structured value that needed masking is written as its masked JSON tree, object keys in alphabetical order; one with nothing to mask keeps its original form. A container nested deeper than the depth limit (default 32) is replaced by [REDACTED] whole, never written unmasked. Set the limit with axio.WithPIIMaxDepth(n), piiMaxDepth in the config file, or PIIConfig.MaxDepth when building a PIIMasker or PIIHook yourself.
The verbose form of an error that formats itself — the errorVerbose beside its message, a stack trace for many errors — is masked and kept. Masking it means scanning it with every pattern: with the default patterns, about 250 µs for a stack of about 2 KB. To omit it instead, never reading it, use axio.WithPIIOmitErrorVerbose(), piiOmitErrorVerbose: true in the config file, or PIIConfig.OmitErrorVerbose; the error is then written by its masked message only.
type User struct {
Email string `json:"email"`
Password string `json:"password"`
}
logger.Info(ctx, "...", axio.Field("user", User{Email: "a@b.com", Password: "x"}))
// -> "user": {"email": "***@***.***", "password": "[REDACTED]"} (with PatternEmail)A hash chain is a structure where each record contains the cryptographic hash of the previous record. Any modification to a record breaks the entire subsequent chain, allowing tampering detection.
Useful for:
- Regulatory compliance (LGPD, SOX, PCI-DSS)
- Tamper-proof audit logs
- Integrity evidence in investigations
Important: Hash chain detects tampering, it doesn't prevent it. Immutability depends on the storage backend.
Each audited JSON line ends with two fields, always last:
| Field | Description |
|---|---|
previous_hash |
Hash of the previous line; empty on the first line of the chain |
hash |
SHA-256 of previous_hash followed by every byte before the trailer |
The hash covers exactly what was written: message, error, stacktrace, service metadata, annotations and whatever custom hooks changed. Hashing, saving the chain state and writing happen under one lock, so the order of the chain is the order of the file, even with many goroutines logging at once.
{"level":"info","timestamp":"2026-09-23T15:16:24.230105632Z","logger":"orders","caller":"app/main.go:26","message":"order created","order_id":"ord_8812","previous_hash":"","hash":"28d41c7b24128b63eed1ed71b77bc63e3f9b9b463af820a3171a0a1927b3f3a8"}Only JSON outputs can be verified. A text output shows the first 6 characters of the hash, for finding the same entry or event in the JSON output.
// Chain state in a local file
logger, _ := axio.New(config,
axio.WithOutputs(axio.MustFile("/var/log/app.log", axio.FormatJSON)),
axio.WithAudit("/var/lib/axio/chain.json"),
)Every Logger audited with the same path in a process, and every event they start, extends one chain, whichever was created first.
An audited Logger needs a JSON output: only JSON lines carry the hashes a log is verified against, so New returns ErrAuditWithoutJSON when every output is text.
New takes an exclusive lock on a file beside the store (chain.json.lock) and holds it while the process runs: a second process using the same store fails in New with ErrChainStoreLocked instead of forking the chain. A FileStore passed through WithAuditChain is locked the same way, and the chain is then loaded from it again, so what another process saved after NewHashChain loaded it is continued rather than forked. Reading the store, as verifying does, takes no lock. The lock uses flock, so Windows, Solaris and AIX have none.
chain, err := axio.NewHashChain(axio.NewFileStore("/var/lib/axio/chain.json"))
if err != nil {
return err
}
file, err := os.Open("/var/log/app.log")
if err != nil {
return err
}
defer file.Close()
// "" because the file starts the chain; for a rotated file, pass the last
// hash of the file before it.
if err := chain.Verify(file, ""); err != nil {
return fmt.Errorf("audit log does not verify: %w", err)
}| Error | Meaning |
|---|---|
ErrHashMismatch |
A line's content changed after it was written |
ErrChainBroken |
A line was removed, moved or inserted, or carries no trailer |
ErrChainIncomplete |
The log ends before the chain: its end was removed, or the whole chain was rewritten |
For rotated files, axio.VerifyLines(reader, previousHash) checks one file and returns the hash of its last line — the previousHash of the next file. chain.Verify is VerifyLines plus the check that the log ends at the chain's last hash. From the terminal, axio verify does both (see below).
Implement ChainStore for custom backends (Redis, PostgreSQL, etc.) and pass the chain with WithAuditChain. Loggers given the same chain, and the events they start, extend one chain:
type ChainStore interface {
Save(sequence uint64, lastHash string) error
Load() (sequence uint64, lastHash string, err error)
}
chain, err := axio.NewHashChain(redisStore)
if err != nil {
return err
}
logger, _ := axio.New(config, axio.WithAuditChain(chain))Distributed tracing allows tracking a request through multiple services. Each operation receives a span identified by:
- trace_id: unique identifier of the complete request
- span_id: unique identifier of this specific operation
With these IDs in logs, it's possible to correlate logs and traces in tools like Jaeger, Tempo, or Zipkin.
Axio uses OpenTelemetry (OTel) as the standard for tracing for the following reasons:
| Factor | OpenTelemetry |
|---|---|
| Standardization | Official CNCF project, industry standard |
| Vendor-neutral | Works with any backend (Jaeger, Zipkin, Datadog, AWS X-Ray) |
| Unification | Traces, metrics, and logs in a single API |
| Adoption | AWS, GCP, Azure, Datadog, Grafana, all support it |
| Community | Active development, extensive documentation |
| Future | Official successor to OpenTracing and OpenCensus |
Considered alternatives:
- Jaeger client: specific to Jaeger, discontinued in favor of OTel
- Zipkin: less flexible, no signal unification
- Proprietary: vendor lock-in
References:
// Via Options (recommended)
logger, _ := axio.New(config, axio.WithTracer(axio.Otel()))
// Via Config (YAML file)
// tracer: otel
// Disable (default)
logger, _ := axio.New(config, axio.WithTracer(axio.NoopTracing()))func handleRequest(w http.ResponseWriter, r *http.Request) {
ctx := r.Context() // contains span from OTel middleware
logger.Info(ctx, "request received")
// Log will include: {"trace_id": "abc123...", "span_id": "def456..."}
}Metrics are numerical values that represent the system state over time. Common types:
- Counters: values that only increase (e.g., total logs)
- Histograms: distribution of values (e.g., hook duration)
Axio emits metrics about the logging process itself, allowing monitoring of volume, errors, and performance.
References:
| Metric | Type | Labels | Description |
|---|---|---|---|
logs.total |
Counter | level |
Total logs emitted |
pii.masked |
Counter | pattern, annotation, logger |
PII occurrences masked |
pii.redacted |
Counter | reason, annotation, logger |
Values redacted whole |
audit.records |
Counter | - | Audit records created |
hook.duration |
Histogram | hook.name, error |
Hook execution duration |
annotation is where in the entry the PII was: message, error, or an annotation's key as the line writes it. logger is the name given with Named, which an event carries from the logger it came from; it is empty for the root logger and its events. reason is why a value was redacted whole: field (its name is sensitive), depth (nested deeper than the limit), token (a JWT or JWE, compact or in JSON serialization) or binary (bytes that are not text). A series exists only for a combination that occurred, so with annotation keys fixed in code there are a few hundred at most; keys built at runtime multiply them.
// Via Options with MeterProvider
provider := otel.GetMeterProvider()
logger, _ := axio.New(config, axio.WithMetrics(provider))
// Via Config (uses global provider with warning)
// metrics:
// enabled: true
// meterName: axio
// meterVersion: 1.0.0The interface a hook implementing MetricsAware receives through SetMetrics. New builds axio's own implementation from the MeterProvider given to WithMetrics, and no option takes another one: to reach another backend, pass a MeterProvider backed by its OpenTelemetry exporter.
type Metrics interface {
LogsTotal(ctx context.Context, level Level)
PIIMasked(ctx context.Context, pattern PIIPattern, origin PIIOrigin, count int)
PIIRedacted(ctx context.Context, reason PIIRedaction, origin PIIOrigin, count int)
AuditRecords(ctx context.Context)
HookDuration(ctx context.Context, hookName string, duration time.Duration, hasError bool)
}Wide events (also called canonical log lines) replace scattered per-step log lines with a single, richly-annotated entry emitted at the end of a unit of work (e.g., an HTTP request). Instead of 5–10 lines per request, one event captures the complete context of what happened.
Wide events omit the log level field — severity is expressed through the event's own fields (status_code, error, etc.), not through traditional log levels.
An event comes from a Logger and writes through it: to its outputs, through its PII masking, hooks and audit chain. Starting one builds none of them and allocates the event alone, so one per request costs little. The event carries the With annotations and the Named name of the logger it came from, is written whatever that logger's level, and writes nothing once the root logger is closed. A JSON output gets the event as JSON; a text output, such as the Console, gets it as text with EVENT in the level column, the same text axio render shows.
logger, err := axio.New(config)
if err != nil {
return err
}
defer logger.Close()
event := logger.Event("checkout")
event.Add("user_id", userID)
event.Add("cart_total", 15999)
event.Add("item_count", 3)
event.Emit(ctx)
// Output: {"timestamp":"...","event":"checkout","user_id":"usr_456","cart_total":15999,"item_count":3,"duration_ms":42}| Method | Description |
|---|---|
logger.Event(name) |
Starts an event written through the logger, with its With annotations and Named name |
Add(key, value) |
Adds a key-value field (thread-safe) |
With(...Annotation) |
Adds annotations, including Annotable types like HTTP |
SetError(err, ...Annotation) |
Records an error with optional detail annotations |
Emit(ctx) |
Writes the event as a single log entry (computes duration_ms, runs hooks; a hook may rename the event); only the first call writes, and none writes after the root logger is closed |
Store the event in the context so downstream handlers can enrich it:
// Middleware: create from the request's logger and store
event := logger.With(axio.Field("request_id", requestID)).Event("http_request")
ctx = axio.WithEvent(ctx, event)
// Handler: enrich from context
event := axio.EventFromContext(ctx)
event.Add("user_id", userID)
event.With(axio.Field("http", axio.HTTP{
Method: r.Method,
URL: r.URL.Path,
StatusCode: 201,
LatencyMS: latencyMS,
}))
// Middleware: emit at end of request
event.Emit(ctx)// Simple error
event.SetError(err)
// Error with structured details
event.SetError(err,
axio.Field("error_code", "card_declined"),
axio.Field("error_retriable", false),
)The options go to New, and every event the logger starts follows them:
// With PII masking, on by default
logger, _ := axio.New(config)
event := logger.Event("user_registration")
// With audit hash chain: an audited logger needs a JSON output
logger, _ := axio.New(config,
axio.WithOutputs(axio.Stdout(axio.FormatJSON)),
axio.WithAudit("/var/lib/axio/chain.json"),
)
event := logger.Event("access_grant")
// With tracing
logger, _ := axio.New(config, axio.WithTracer(axio.Otel()))
event := logger.Event("http_request")go install github.com/pragmabits/axio/cmd/axio@latestThe command is a module of its own, github.com/pragmabits/axio/cmd/axio, so importing the library does not bring its Cobra dependency along.
Logs meant for machines are JSON. axio render turns them back into the text a person reads on a terminal — the same text the Console output writes, colors included, except where JSON holds a field differently: a time.Duration annotation shows as the milliseconds JSON holds (1500, where the Console writes "1.5s"), and a time.Time one as its JSON timestamp ("2026-01-02T03:04:05Z", where the Console writes "2026-01-02T03:04:05.000Z"). JSON does not say what type a value was.
kubectl logs -f deploy/checkout | axio render
kubectl logs -f -l app=checkout --prefix | axio render
docker compose logs -f checkout | axio render
journalctl -u checkout -o cat -f | axio render
axio render /var/log/checkout.log
kubectl logs deploy/checkout | axio render | grep -E 'WARN|ERROR'
kubectl logs deploy/checkout | axio render --color=always | less -R- Reads files in order, or standard input;
-also names standard input - Writes each line as soon as it reads it, so it follows
-fstreams - Lines that are not axio entries pass through unchanged; a prefix before the JSON (pod name, compose service) stays in front
- Wide events show
EVENTin the level column --color=auto|always|never:autocolors only a terminal and respectsNO_COLOR--utc: timestamps in UTC instead of the local time zoneaxio completion bash|zsh|fish|powershellgenerates shell completion
Checks an audited JSON log against the chain stored by WithAudit: every line's hash matches the line, every line continues the one before it, and the log ends where the chain ends.
axio verify --store /var/lib/axio/chain.json /var/log/app.log
axio verify --store chain.json app.log.2 app.log.1 app.log # rotated files, oldest first
axio verify --store chain.json --previous-hash "$(tail -1 app.log.1 | jq -r .hash)" app.log
kubectl logs deploy/payments | axio verify --store chain.jsonverified: the log reaches the chain's last hash 550e01 # exit 0
axio: app.log.1: hash mismatch: line 2 # exit 1
axio: app.log: chain integrity compromised: line 1 does not continue the line before it
axio: log does not reach the chain's last hash: log ends at "f0503d", chain at "550e01"
--storeis required;--previous-hashis the hash of the line before the first one, when the oldest file you have is not the first of the chain- Verify a log that is no longer being written: while a logger is still writing, the chain may end past the last line read
- Use structured fields for data; message is human summary
- Prefer stable keys:
user_id,order_id,tenant_id - Avoid dynamic keys:
field_123,user_email_john@...
| Level | Use when |
|---|---|
| Debug | Technical details, temporary |
| Info | Normal events, flow milestones |
| Warn | Anomalies that don't interrupt |
| Error | Real operation failure |
Rule: Log error once, at the system boundary (handler, job, consumer).
Always pass context.Context and add identifiers:
request_id/correlation_iduser_id,tenant_idtrace_id,span_id(via tracing)
- Keep PII masking on: it is the default, and
WithPIIDisabledis for services that log no personal data - Never log: password, token, secret, private key
- If you need the payload, log hash or ID, not the content
- Avoid logs in hot loops; prefer aggregation
- Don't build large strings/maps unnecessarily
- In production: JSON + agent collection
- Finding the caller costs about 2 µs: half of a line with PII masking off, a third of one with it on; where the source location is not needed,
omitCaller: trueoraxio.WithOmitCaller()drops it
Fields with unlimited values (email, payloads) explode indexes. Maintain:
- Stable IDs (user, order, tenant)
- Status codes, methods, endpoints
- Latency in milliseconds
For critical operations, use WithAudit with a JSON output and combine with reliable storage.
logger.Info(ctx, "request completed",
axio.Field("http", axio.HTTP{
Method: r.Method,
URL: r.URL.Path,
StatusCode: statusCode,
LatencyMS: latencyMS,
ClientIP: r.RemoteAddr,
}),
axio.Field("request_id", requestID),
axio.Field("user_id", userID),
)- Does the message summarize the event?
- Are fields consistent and stable?
- Is the level correct?
- Is there exposed PII?
- Was the error logged only once?
Goal: Measure latency, success/error, track requests.
| Event | Level | Suggested fields |
|---|---|---|
| Request completed | Info | method, url, status_code, latency, user_agent, client_ip (from axio.HTTP), request_id, user_id, trace_id |
| Domain error | Warn/Error | +operation, +entity, +error |
logger.Info(ctx, "request completed", axio.Field("http", axio.HTTP{...}), axio.Field("request_id", id))Goal: Know when it started, finished, how much it processed.
| Event | Level | Suggested fields |
|---|---|---|
| Job started | Info | job_name, job_id |
| Job completed | Info | +items_total, +items_ok, +items_failed, +duration_ms |
| Item error | Warn | +item_id, +error (sampled) |
logger.Info(ctx, "job completed",
axio.Field("job_name", "reconcile_payments"),
axio.Field("items_ok", okCount),
axio.Field("items_failed", failedCount),
)Goal: Track consumption, retries, failures per message.
| Event | Level | Suggested fields |
|---|---|---|
| Message processed | Info/Debug | queue, message_id, latency_ms |
| Message failure | Warn/Error | +retry_count, +error |
Goal: Visibility of latency and failures in third parties.
| Event | Level | Suggested fields |
|---|---|---|
| External call | Info/Debug | provider, operation, status_code, latency_ms |
| Timeout/error | Warn | +attempt, +timeout_ms |
Goal: Audit execution and result.
| Event | Level | Suggested fields |
|---|---|---|
| Start | Info | command, args_redacted |
| End | Info | +exit_code, +duration_ms, +output_count |
Wrong:
logger.Info(ctx, fmt.Sprintf("user=%s status=%d", userID, statusCode))Correct:
logger.Info(ctx, "request completed",
axio.Field("user_id", userID),
axio.Field("status_code", statusCode),
)Wrong:
logger.Info(ctx, fmt.Sprintf("payload=%+v", payload))Correct:
logger.Info(ctx, "payload received",
axio.Field("payload_id", payload.ID),
axio.Field("payload_size", len(payload.Data)),
)Wrong:
// repository
if err != nil {
logger.Error(ctx, err, "failed to insert")
return err
}Correct:
// repository
if err != nil {
return fmt.Errorf("insert order: %w", err)
}
// handler (system boundary)
if err != nil {
logger.Error(ctx, err, "failed to create order")
}Wrong:
for _, item := range items {
logger.Debug(ctx, "processing item", axio.Field("item_id", item.ID))
}Correct:
logger.Info(ctx, "batch processed",
axio.Field("items_total", len(items)),
axio.Field("items_ok", okCount),
axio.Field("items_failed", failedCount),
)Wrong:
logger.Info(ctx, "login", axio.Field("email", user.Email))Correct:
logger.Info(ctx, "login", axio.Field("user_id", user.ID))Wrong:
logger.Error(ctx, err, "error")Correct:
logger.Error(ctx, err, "failed to confirm payment",
axio.Field("order_id", order.ID),
)| Error | Cause | Solution |
|---|---|---|
ErrInvalidEnvironment |
Invalid Environment value | Use production, staging, or development |
ErrInvalidLevel |
Invalid Level value | Use debug, info, warn, or error |
ErrInvalidFormat |
Invalid Format value | Use json or text |
ErrInvalidOutputType |
Invalid OutputType value | Use console, stdout, or file |
ErrIncompatibleOutputs |
AgentMode with non-stdout/json output | In AgentMode, use only stdout + json |
ErrFileOutputNoPath |
File output type without path | Specify path in OutputConfig |
ErrAuditWithoutPath |
Audit enabled without storePath | Specify storePath in AuditConfig |
ErrAuditWithoutJSON |
Audited Logger with only text outputs | Add a JSON output; only JSON lines verify |
ErrInvalidPIIMaxDepth |
Negative PII masking depth | Use 0 for the default, or a positive depth |
ErrInvalidPIIIdentifierShape |
PII identifier shape that is not RE2 | Fix the expression |
ErrBroadPIIIdentifierShape |
Shape that could match a bare number | Write the letters around the number as they are |
ErrInvalidTracer |
Invalid TracerType value | Use otel or noop |
ErrLoadConfig |
Failed to read config file | Check path and permissions |
ErrUnknownFormat |
Unknown file extension | Use .yaml, .yml, .json, or .toml |
ErrUnmarshalConfig |
Failed to parse config | Check file syntax |
ErrApplyOption |
Failed to apply Option | Check Option parameters |
ErrValidateConfig |
Invalid configuration after Options | Check value combination |
ErrBuildOutputs |
Failed to create outputs | Check file paths |
ErrBuildHooks |
Failed to create hooks | Check PIICustomPatterns regex |
ErrBuildMetrics |
Failed to build metrics | Check MeterProvider configuration |
ErrBuildAudit |
Failed to build audit chain | Check the store path and its permissions |
ErrBuildEngine |
Failed to build logging engine | Check output and config combination |
ErrOpenFile |
Failed to open log file | Check path and permissions |
ErrOutputClosed |
File output closed a second time | Close each output once |
ErrOutputInUse |
File output given to a second owner | Open one output per Logger |
ErrRotationConflict |
Path already open with another rotation | One rotation per path in the process |
ErrRotatingFileLocked |
Another process holds the rotating file | One process per rotating file |
ErrLoadChainState |
Failed to load chain state | Check chain file |
ErrSaveChainState |
Failed to save chain state | Check write permissions |
ErrMarshalChainState |
Failed to marshal chain state | Internal serialization error |
ErrUnmarshalChainState |
Failed to unmarshal chain state | Chain file corrupted or invalid format |
ErrHashMismatch |
A line's hash doesn't match it | The line changed after it was written |
ErrChainBroken |
Chain integrity compromised | A line was removed, moved or inserted |
ErrChainIncomplete |
Log ends before the chain | End removed, or the whole chain rewritten |
ErrNilAuditChain |
Chain passed to WithAuditChain is nil | Pass a chain from NewHashChain |
ErrChainStoreLocked |
Another process holds the chain store | One process per store; give each its own path |
ErrNilMetricsProvider |
Metrics provider is nil | Pass a valid MeterProvider |
ErrCreateMetric |
Failed to create OTel instrument | Check provider configuration |
ErrNilTracer |
Tracer passed to WithTracer is nil | Pass a non-nil Tracer or omit the option |
ErrLoggerClosed |
Logger has already been closed | Idempotent guard; check with errors.Is |
ErrLoggerNotRoot |
Close called on a forked Logger | Only the root from New can be closed |