Repository navigation
Expand file tree
/
Copy pathaxio.go
More file actions
332 lines (317 loc) · 11.4 KB
/
Copy pathaxio.go
File metadata and controls
332 lines (317 loc) · 11.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
// Package axio provides a high-performance structured logger for Go applications.
//
// Axio offers enterprise-grade features such as PII masking, hash chain auditing,
// and integration with OpenTelemetry for distributed tracing, exposed through a
// small, stable public API that intentionally hides the underlying engine.
//
// # Basic Usage
//
// To create a simple logger:
//
// config := axio.Config{
// ServiceName: "my-service",
// ServiceVersion: "1.0.0",
// Environment: axio.EnvironmentDevelopment,
// Level: axio.LevelInfo,
// }
// logger, err := axio.New(config)
// if err != nil {
// log.Fatal(err)
// }
// logger.Info(ctx, "application started")
//
// # Configuration with Options
//
// The logger can be configured using the functional options pattern:
//
// logger, err := axio.New(config,
// axio.WithOutputs(axio.Stdout(axio.FormatJSON)),
// axio.WithTracer(axio.Otel()),
// )
//
// # Multiple Outputs
//
// Axio supports multiple simultaneous outputs with different formats:
//
// logger, err := axio.New(config,
// axio.WithOutputs(
// axio.Console(axio.FormatText),
// axio.Stdout(axio.FormatJSON),
// axio.MustFile("/var/log/app.log", axio.FormatJSON),
// ),
// )
//
// # PII Masking
//
// Every Logger and Event masks sensitive personal data unless [WithPIIDisabled]
// or [Config.PIIDisabled] turns masking off. CPF, CNPJ and credit cards are
// masked by default; e-mails ([PatternEmail]) and phones ([PatternPhone]) are
// masked when [WithPII] lists their patterns:
//
// - CPF: 123.456.789-01 → ***.***.***-**
// - CNPJ: 12.345.678/0001-90 → **.***.***/****-**
// - Credit cards: 1234-5678-9012-3456 → ****-****-****-****
// - E-mails: user@example.com → ***@***.***
// - Brazilian phones: (11) 99999-9999 → (**) *****-****
//
// Example:
//
// logger, _ := axio.New(config)
// logger.Info(ctx, "Customer CPF: 123.456.789-01")
// // Output: "Customer CPF: ***.***.***-**"
//
// Masking covers every value the caller hands a line — the message, the error
// and each annotation, structs and maps included; see [PIIMasker.MaskFields].
//
// A whole UUID is not PII: no built-in pattern matches inside it, so an
// identifier is never masked as a card or a phone number; see
// [PIIMasker.MaskString].
//
// # Hash Chain Auditing
//
// For logs that require integrity proof (LGPD, SOX, PCI-DSS compliance):
//
// logger, _ := axio.New(config,
// axio.WithOutputs(axio.MustFile("/var/log/app.log", axio.FormatJSON)),
// axio.WithAudit("/var/lib/axio/chain.json"),
// )
//
// Each JSON line ends with previous_hash and hash, the SHA-256 of the previous
// hash followed by the line's own bytes: a chain that detects any change,
// removal or reordering. [HashChain.Verify] checks a log against the chain.
// An audited Logger needs a JSON output, and a [FileStore] is held by one
// process at a time.
//
// # OpenTelemetry Integration
//
// Axio automatically adds trace_id and span_id to logs when
// configured with a tracer:
//
// logger, _ := axio.New(config, axio.WithTracer(axio.Otel()))
//
// # Structured Annotations
//
// Contextualize your logs with typed annotations:
//
// logger.Info(ctx, "order created successfully",
// axio.Field("user_id", userID),
// axio.Field("tenant", tenantName),
// axio.Field("http", axio.HTTP{
// Method: "POST",
// URL: "/api/v1/orders",
// StatusCode: 201,
// LatencyMS: 45,
// }),
// )
//
// # Agent Mode
//
// For environments with log collection agents (Promtail, Fluent Bit, Filebeat):
//
// logger, _ := axio.New(config, axio.WithAgentMode())
//
// This forces JSON output to stdout, optimized for collection by external agents.
//
// # Log Levels
//
// Axio supports four severity levels:
//
// - [LevelDebug]: Detailed information for debug
// - [LevelInfo]: Informational events about normal operations
// - [LevelWarn]: Anomalous conditions that deserve attention
// - [LevelError]: Errors that affect operation
//
// # Environments
//
// The logger behavior varies according to the execution environment:
//
// - [EnvironmentDevelopment]: Colored console, no stack traces
// - [EnvironmentStaging]: JSON, with stack traces on errors
// - [EnvironmentProduction]: JSON, with stack traces on errors
package axio
import (
"context"
"fmt"
"strings"
)
// Logger defines the main interface for structured logging.
//
// The interface provides methods for different severity levels
// (Debug, Info, Warn, Error) and supports contextualization through
// structured annotations.
//
// Logging methods accept a [context.Context] as the first parameter,
// allowing automatic integration with distributed tracing when a
// [Tracer] is configured.
//
// Example:
//
// logger, _ := axio.New(settings)
//
// // Simple log
// logger.Info(ctx, "user authenticated")
//
// // Log with annotations of its own
// logger.Info(ctx, "order created",
// axio.Field("user_id", userID),
// axio.Field("http", axio.HTTP{Method: "POST", URL: "/api/orders"}),
// )
//
// // A logger that attaches annotations to every entry it writes
// requestLogger := logger.With(axio.Field("request_id", requestID))
//
// // Error log
// logger.Error(ctx, err, "failed to process payment")
type Logger interface {
// Named creates a sub-logger with an additional name.
// Names are concatenated with dots (e.g., "app.http.handler").
Named(string) Logger
// Debug logs a debug message with the given annotations. The message is
// written as given; it is never formatted.
Debug(context.Context, string, ...Annotation)
// Info logs an informational message with the given annotations.
Info(context.Context, string, ...Annotation)
// Warn logs a warning with the associated error and the given annotations.
Warn(context.Context, error, string, ...Annotation)
// Error logs an error with the associated error and the given annotations.
Error(context.Context, error, string, ...Annotation)
// With returns a logger that attaches the annotations to every entry it
// writes, before the annotations given to each call.
With(...Annotation) Logger
// Event starts a wide [Event] with the given name, written through this
// logger when [Event.Emit] is called. The event owns nothing: it writes to
// the logger's outputs, through its hooks and its audit chain, and builds
// none of them, so starting one allocates the event alone. It carries the
// annotations of [Logger.With] before its own and the name of
// [Logger.Named], and it is written whatever the logger's level. After the
// root logger is closed, Emit writes nothing.
//
// Example:
//
// event := logger.Event("checkout")
// ctx = axio.WithEvent(ctx, event)
// defer event.Emit(ctx)
// event.Add("cart_total", cartTotal)
Event(name string) *Event
// Close releases resources owned by the root logger: it syncs and closes
// its outputs, which releases the files and their locks. It should be
// called when the logger is no longer needed, typically via defer in main.
//
// Only the root Logger (returned by [New]) owns resources. Calling Close
// on a logger produced by [Logger.Named] or [Logger.With] returns
// [ErrLoggerNotRoot] and leaves all resources untouched. A second Close
// on the root returns [ErrLoggerClosed]. After the root is closed, log
// calls on the root and on every fork become silent no-ops, and so does
// [Event.Emit] on every event they started. Close waits for the writes
// already under way, and a line or event that reaches its write after Close
// counts as one made after it and writes nothing: no write fails on a
// closed output, and with auditing the chain never runs past the log.
Close() error
}
// Environment represents the execution environment of the application.
//
// The environment affects the default behavior of the logger:
// - Output format (JSON vs colored text)
// - Inclusion of stack traces
// - Service metadata fields
type Environment string
const (
// EnvironmentProduction indicates production environment.
// JSON logs with stack traces on errors and service metadata.
EnvironmentProduction Environment = "production"
// EnvironmentStaging indicates staging environment.
// Behavior similar to production for realistic testing.
EnvironmentStaging Environment = "staging"
// EnvironmentDevelopment indicates development environment.
// Colored text logs for better readability during development.
EnvironmentDevelopment Environment = "development"
)
// Validate checks whether the environment is a valid value.
//
// Returns [ErrInvalidEnvironment] if the value is not one of the defined environments.
func (e Environment) Validate() error {
switch e {
case EnvironmentProduction, EnvironmentStaging, EnvironmentDevelopment:
return nil
default:
return fmt.Errorf("%w: %s", ErrInvalidEnvironment, e)
}
}
// UnmarshalText implements [encoding.TextUnmarshaler] for validation during parsing.
func (e *Environment) UnmarshalText(text []byte) error {
return unmarshalEnum(text, e)
}
// Level represents the severity of a log entry.
//
// Levels follow the standard logging convention, from least to most severe:
// Debug < Info < Warn < Error.
//
// Logs with a level below the configured [Config.Level] are discarded.
type Level string
const (
// LevelDebug indicates debug logs with detailed information.
// Typically disabled in production due to volume.
LevelDebug Level = "debug"
// LevelInfo indicates informational logs about normal operations.
// Default level for most applications in production.
LevelInfo Level = "info"
// LevelWarn indicates anomalous conditions that deserve attention.
// The application keeps running, but something unexpected occurred.
LevelWarn Level = "warn"
// LevelError indicates errors that affect operation.
// Requires immediate attention from the operations team.
LevelError Level = "error"
)
// Validate checks whether the level is a valid value.
//
// Returns [ErrInvalidLevel] if the value is not one of the defined levels.
func (l Level) Validate() error {
switch l {
case LevelDebug, LevelInfo, LevelWarn, LevelError:
return nil
default:
return fmt.Errorf("%w: %s", ErrInvalidLevel, l)
}
}
// UnmarshalText implements [encoding.TextUnmarshaler] for validation during parsing.
func (l *Level) UnmarshalText(text []byte) error {
return unmarshalEnum(text, l)
}
// Format defines the encoding format of log output.
type Format string
const (
// FormatJSON produces structured JSON logs.
// Ideal for log aggregation systems such as Loki, Elasticsearch, or Splunk.
FormatJSON Format = "json"
// FormatText produces readable colored text logs.
// Ideal for development and local debugging.
FormatText Format = "text"
)
// Validate checks whether the format is a valid value.
//
// Returns [ErrInvalidFormat] if the value is not one of the defined formats.
func (f Format) Validate() error {
switch f {
case FormatJSON, FormatText:
return nil
default:
return fmt.Errorf("%w: %s", ErrInvalidFormat, f)
}
}
// UnmarshalText implements [encoding.TextUnmarshaler] for validation during parsing.
func (f *Format) UnmarshalText(text []byte) error {
return unmarshalEnum(text, f)
}
// unmarshalEnum sets target to text, trimmed, once the enum's Validate accepts
// it, and leaves target alone otherwise.
func unmarshalEnum[T interface {
~string
Validate() error
}](text []byte, target *T) error {
value := T(strings.TrimSpace(string(text)))
if err := value.Validate(); err != nil {
return err
}
*target = value
return nil
}