Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ErrorLogEntry ¶
type ErrorLogEntry struct {
LogEntry
ErrorClass string `json:"error_class"`
ErrorMessage string `json:"error_message"`
StackTrace string `json:"stack_trace,omitempty"`
}
ErrorLogEntry represents a structured log entry dedicated to error events.
It extends LogEntry by adding metadata specific to runtime errors, enabling better diagnostics, filtering, and categorization of failures during execution.
Fields:
- ErrorClass: a short identifier that classifies the type of error (e.g., "ValidationError", "IOError"). Derived via internal heuristics or conventions.
- ErrorMessage: the error message returned by the error object. Also used as the main log message.
- StackTrace: an optional string representation of the stack trace where the error occurred. Included only if available and supported by the error type or logger configuration.
func NewErrorLogEntry ¶
func NewErrorLogEntry(ctx context.Context, err error, additionalData ...map[string]any) ErrorLogEntry
NewErrorLogEntry creates a new ErrorLogEntry from a given error and optional metadata.
This constructor extracts trace and build context, classifies the error, and optionally includes a stack trace if available. It also merges any additional data provided for enrichment.
Parameters:
- ctx (context.Context): the execution context from which trace and build metadata are extracted.
- err (error): the error instance to log. Must not be nil.
- additionalData (...map[string]any): optional variadic key-value maps to include in AdditionalData.
Returns:
- ErrorLogEntry: a structured and enriched log entry representing the error.
type K8SLogEntry ¶
type K8SLogEntry struct {
LogEntry
ClusterName string `json:"cluster_name"`
Namespace string `json:"namespace"`
PodName string `json:"pod_name"`
Container string `json:"container"`
NodeName string `json:"node_name"`
}
K8SLogEntry represents a structured log entry containing Kubernetes-specific context.
This log type extends LogEntry with metadata related to the Kubernetes execution environment, allowing better correlation, debugging, and traceability across clusters, pods, and containers.
Fields:
- ClusterName: the name of the Kubernetes cluster where the log was generated.
- Namespace: the Kubernetes namespace of the pod emitting the log.
- PodName: the name of the pod responsible for the log entry.
- Container: the name of the container within the pod emitting the log.
- NodeName: the name of the Kubernetes node hosting the pod.
func NewK8SLogEntry ¶
func NewK8SLogEntry( ctx context.Context, clusterName, namespace, podName, container, nodeName string, level Level.LogLevel, message string, additionalData ...map[string]any, ) K8SLogEntry
NewK8SLogEntry creates a new K8SLogEntry enriched with Kubernetes context.
This constructor extends the base log structure with Kubernetes-specific fields, while also applying the standard metadata enrichment (timestamp, trace, build info, etc.) from LogEntry.
Parameters:
- ctx (context.Context): the execution context for trace/build metadata extraction.
- clusterName (string): the name of the Kubernetes cluster.
- namespace (string): the Kubernetes namespace of the emitting pod.
- podName (string): the name of the pod that produced the log.
- container (string): the name of the container inside the pod.
- nodeName (string): the name of the node hosting the pod.
- level (Level.LogLevel): the severity level of the log.
- message (string): the log message content.
- additionalData (...map[string]any): optional structured metadata for enrichment.
Returns:
- K8SLogEntry: a structured and context-rich log entry for Kubernetes environments.
type LambdaBeginLogEntry ¶
type LambdaBeginLogEntry struct {
LogEntry
FunctionName string `json:"function_name"`
RequestID string `json:"request_id"`
}
LambdaBeginLogEntry represents the initial log entry for an AWS Lambda function invocation.
This entry captures the moment the function begins executing and includes identifying information such as the function name and AWS request ID.
Fields:
- FunctionName: the name of the AWS Lambda function being executed.
- RequestID: the unique identifier for the current Lambda invocation (provided by AWS).
func NewLambdaBeginLogEntry ¶
func NewLambdaBeginLogEntry( ctx context.Context, functionName, requestID string, additionalData ...map[string]any, ) LambdaBeginLogEntry
NewLambdaBeginLogEntry creates a new LambdaBeginLogEntry with execution context and metadata.
This constructor is intended to be used at the start of a Lambda function's execution to capture the timestamp, trace information, and identifying metadata.
Parameters:
- ctx (context.Context): the execution context for metadata extraction.
- functionName (string): the name of the Lambda function.
- requestID (string): the AWS request ID associated with the invocation.
- additionalData (...map[string]any): optional metadata to enrich the log entry.
Returns:
- LambdaBeginLogEntry: a fully structured log entry marking the start of the function.
type LambdaEndLogEntry ¶
type LambdaEndLogEntry struct {
LogEntry
FunctionName string `json:"function_name"`
RequestID string `json:"request_id"`
DurationMs int64 `json:"duration_ms"`
}
LambdaEndLogEntry represents the final log entry for an AWS Lambda function invocation.
It is used to capture the end of execution along with the duration of the invocation, calculated automatically based on the timestamp of the corresponding LambdaBeginLogEntry.
Fields:
- FunctionName: the name of the AWS Lambda function being executed.
- RequestID: the unique identifier for the current Lambda invocation.
- DurationMs: the execution time in milliseconds, computed as the difference between the start and end timestamps.
func NewLambdaEndLogEntryFromBegin ¶
func NewLambdaEndLogEntryFromBegin( begin LambdaBeginLogEntry, additionalData ...map[string]any, ) LambdaEndLogEntry
NewLambdaEndLogEntryFromBegin creates a LambdaEndLogEntry based on a corresponding begin entry, automatically calculating the duration of the invocation.
This constructor should be called at the end of the Lambda execution. It uses the timestamp from the LambdaBeginLogEntry to calculate the duration in milliseconds.
Parameters:
- begin (LambdaBeginLogEntry): the previously created begin log entry.
- additionalData (...map[string]any): optional metadata to include in the final log.
Returns:
- LambdaEndLogEntry: a structured log entry representing the end of execution with duration.
type LogEntry ¶
type LogEntry struct {
Context context.Context `json:"-"`
Timestamp time.Time `json:"timestamp"`
Level Level.LogLevel `json:"level"`
EventType string `json:"event_type"`
Message string `json:"message"`
// Trace metadata
TraceID string `json:"trace_id,omitempty"`
SpanID string `json:"span_id,omitempty"`
ParentSpanID string `json:"parent_span_id,omitempty"`
// Build information
Version string `json:"version,omitempty"`
CommitHash string `json:"commit_hash,omitempty"`
BuildTime string `json:"build_time,omitempty"`
// Library metadata
LibraryName string `json:"library_name,omitempty"`
LibraryVersion string `json:"library_version,omitempty"`
LibraryCommit string `json:"library_commit,omitempty"`
LibraryBuildTime string `json:"library_build_time,omitempty"`
// User-defined metadata
AdditionalData map[string]any `json:"additional_data,omitempty"`
}
LogEntry represents a structured and enriched log message emitted by the application.
It captures essential metadata such as timestamp, severity level, trace identifiers, and additional diagnostic fields that help with observability, debugging, and auditing.
Fields:
- Context: the execution context. Used internally for extracting trace and build metadata. This field is not serialized to JSON.
- Timestamp: UTC timestamp of when the log entry was created.
- Level: severity level of the log (trace, info, warn, error).
- EventType: a string label that categorizes the type of log entry. Defaults to "LogEntry", but can be overridden by embedding structs.
- Message: the human-readable message describing the event or situation.
Trace fields:
- TraceID: unique identifier for the current trace, if available.
- SpanID: identifier for the current span within the trace.
- ParentSpanID: identifier of the parent span, if applicable.
Build information:
- Version: the version of the application at build time.
- CommitHash: the git commit hash associated with the build.
- BuildTime: the timestamp of the build process.
Library metadata:
- LibraryName: name of the logging library emitting the log.
- LibraryVersion: version of the library in use.
- LibraryCommit: commit hash of the library version.
- LibraryBuildTime: timestamp when the library was built.
Extensibility:
- AdditionalData: optional user-defined key-value pairs to enrich the log. Merged from the variadic map arguments passed to the constructor.
func NewLogEntry ¶
func NewLogEntry(ctx context.Context, level Level.LogLevel, message string, additionalData ...map[string]any) LogEntry
NewLogEntry creates a new LogEntry with automatic enrichment from context and build metadata.
This constructor centralizes the creation of log entries and ensures consistent formatting across the application. It extracts trace and build information from the provided context, attaches standardized metadata, and optionally merges any additional structured data.
Parameters:
- ctx (context.Context): the execution context used to extract trace IDs and other metadata.
- level (Level.LogLevel): the severity level of the log entry (e.g., LogLevelInfo, LogLevelError).
- message (string): a human-readable description of the log event.
- additionalData (...map[string]any): optional variadic key-value maps that will be merged into the final `AdditionalData` field.
Returns:
- LogEntry: a fully enriched structured log entry ready to be serialized or dispatched.
type MessageAcknowledgedLogEntry ¶
type MessageAcknowledgedLogEntry struct {
LogEntry
MessageID string `json:"message_id"`
Topic string `json:"topic"`
Consumer string `json:"consumer"`
DurationMs int64 `json:"duration_ms"`
}
MessageAcknowledgedLogEntry represents a log entry indicating successful processing of a message.
This entry includes the same identifying fields as the received log, along with the duration between reception and acknowledgment.
Fields:
- MessageID: the unique identifier of the message.
- Topic: the topic or queue where the message was published.
- Consumer: the name or identifier of the consumer that processed the message.
- DurationMs: the time taken to process the message, in milliseconds.
func NewMessageAcknowledgedLogEntryFromReceived ¶
func NewMessageAcknowledgedLogEntryFromReceived( received MessageReceivedLogEntry, additionalData ...map[string]any, ) MessageAcknowledgedLogEntry
NewMessageAcknowledgedLogEntryFromReceived creates a log entry indicating successful processing of a previously received message, automatically calculating the duration.
Parameters:
- received (MessageReceivedLogEntry): the original message receipt log entry.
- additionalData (...map[string]any): optional metadata to enrich the log.
Returns:
- MessageAcknowledgedLogEntry: a structured log with timing information.
type MessageReceivedLogEntry ¶
type MessageReceivedLogEntry struct {
LogEntry
MessageID string `json:"message_id"`
Topic string `json:"topic"`
Consumer string `json:"consumer"`
}
MessageReceivedLogEntry represents a log entry indicating that a message has been received by a consumer from a given topic.
This entry captures key metadata that identifies the message, the topic it was published to, and the consumer that received it. It serves as the starting point for tracking message lifecycle.
Fields:
- MessageID: the unique identifier of the message.
- Topic: the topic or queue where the message was published.
- Consumer: the name or identifier of the consumer that received the message.
func NewMessageReceivedLogEntry ¶
func NewMessageReceivedLogEntry( ctx context.Context, messageID, topic, consumer string, additionalData ...map[string]any, ) MessageReceivedLogEntry
NewMessageReceivedLogEntry creates a log entry marking the moment a message is received by a consumer.
Parameters:
- ctx (context.Context): context used to enrich the log with trace/build info.
- messageID (string): the unique ID of the received message.
- topic (string): the topic or queue from which the message was received.
- consumer (string): the name of the receiving consumer.
- additionalData (...map[string]any): optional metadata to enrich the log.
Returns:
- MessageReceivedLogEntry: a structured log entry for message receipt.
type MessageRejectedLogEntry ¶
type MessageRejectedLogEntry struct {
LogEntry
MessageID string `json:"message_id"`
Topic string `json:"topic"`
Consumer string `json:"consumer"`
Reason string `json:"reason"`
DurationMs int64 `json:"duration_ms"`
}
MessageRejectedLogEntry represents a log entry indicating that a message was rejected during processing.
This entry includes metadata about the message and consumer, along with the rejection reason and duration of processing.
Fields:
- MessageID: the unique identifier of the message.
- Topic: the topic or queue where the message was published.
- Consumer: the name or identifier of the consumer that rejected the message.
- Reason: the reason for rejecting the message.
- DurationMs: the time spent processing the message before rejection, in milliseconds.
func NewMessageRejectedLogEntryFromReceived ¶
func NewMessageRejectedLogEntryFromReceived( received MessageReceivedLogEntry, reason string, additionalData ...map[string]any, ) MessageRejectedLogEntry
NewMessageRejectedLogEntryFromReceived creates a log entry indicating failed processing of a message, capturing the rejection reason and processing duration.
Parameters:
- received (MessageReceivedLogEntry): the original message receipt log entry.
- reason (string): the reason for rejecting the message.
- additionalData (...map[string]any): optional metadata to enrich the log.
Returns:
- MessageRejectedLogEntry: a structured log with rejection details and timing.
type OperationRequestLogEntry ¶
type OperationRequestLogEntry struct {
LogEntry
OperationName string `json:"operation_name"`
Resource string `json:"resource"`
RequestID string `json:"request_id"`
Path string `json:"path"`
HTTPMethod string `json:"http_method"`
}
OperationRequestLogEntry represents the log entry for the start of a logical application operation, such as a RESTful request or command execution.
It contains identifying information about the operation being performed, including its name, associated resource, and request metadata.
Fields:
- OperationName: the logical name of the operation being performed (e.g., "CreateUser").
- Resource: the type of entity or subsystem being acted upon (e.g., "user", "order").
- RequestID: a unique identifier for the operation invocation, used for correlation.
- Path: the HTTP path or route associated with the operation.
- HTTPMethod: the HTTP method (GET, POST, etc.) used in the request.
func NewOperationRequestLogEntry ¶
func NewOperationRequestLogEntry( ctx context.Context, operationName, resource, requestID, path, httpMethod string, additionalData ...map[string]any, ) OperationRequestLogEntry
NewOperationRequestLogEntry creates a structured log entry for the start of an operation.
This constructor captures identifying metadata and automatically enriches the log with trace, version, and build information from the context.
Parameters:
- ctx (context.Context): the context used for trace and metadata enrichment.
- operationName (string): a descriptive name for the logical operation.
- resource (string): the domain or entity the operation applies to.
- requestID (string): a unique ID used to correlate request/response pairs.
- path (string): the HTTP route or endpoint involved.
- httpMethod (string): the HTTP verb used in the request.
- additionalData (...map[string]any): optional user-defined metadata to enrich the log.
Returns:
- OperationRequestLogEntry: a structured entry representing the start of the operation.
type OperationResponseLogEntry ¶
type OperationResponseLogEntry struct {
LogEntry
OperationName string `json:"operation_name"`
Resource string `json:"resource"`
RequestID string `json:"request_id"`
HTTPStatus int `json:"http_status"`
DurationMs int64 `json:"duration_ms"`
}
OperationResponseLogEntry represents the log entry for the end of an application operation, capturing its outcome and the time taken to execute.
Fields:
- OperationName: the same logical name used in the request log.
- Resource: the same resource context used in the request log.
- RequestID: a unique identifier matching the original request.
- HTTPStatus: the HTTP status code returned as a result of the operation.
- DurationMs: the time elapsed from the request to the response, in milliseconds.
func NewOperationResponseLogEntry ¶
func NewOperationResponseLogEntry( req OperationRequestLogEntry, httpStatus int, additionalData ...map[string]any, ) OperationResponseLogEntry
NewOperationResponseLogEntry creates a structured log entry representing the completion of an operation.
It calculates the duration of the operation by comparing the current time with the timestamp in the original request log. Additional metadata can be attached if needed.
Parameters:
- req (OperationRequestLogEntry): the original operation request entry.
- httpStatus (int): the resulting HTTP status code of the operation.
- additionalData (...map[string]any): optional user-defined metadata.
Returns:
- OperationResponseLogEntry: a log entry that includes timing and result details.
type TraceBeginLogEntry ¶
TraceBeginLogEntry represents the beginning of a trace section in the application flow.
This log entry is typically used to mark the start of a measurable unit of work, allowing correlation with a matching TraceEndLogEntry to calculate total duration.
Fields:
- Name: a human-readable label identifying the trace section (e.g., "LoadUserProfile").
func NewTraceBeginLogEntry ¶
func NewTraceBeginLogEntry( ctx context.Context, name string, additionalData ...map[string]any, ) TraceBeginLogEntry
NewTraceBeginLogEntry creates a new trace entry to mark the start of a measurable block of execution.
This entry records the timestamp and contextual metadata, allowing future correlation with a corresponding TraceEndLogEntry to compute total execution time.
Parameters:
- ctx (context.Context): the execution context used for trace and metadata enrichment.
- name (string): a label identifying the trace section.
- additionalData (...map[string]any): optional structured metadata for enrichment.
Returns:
- TraceBeginLogEntry: a structured entry marking the start of a traceable operation.
type TraceEndLogEntry ¶
type TraceEndLogEntry struct {
LogEntry
Name string `json:"name"`
DurationMs int64 `json:"duration_ms"`
}
TraceEndLogEntry represents the end of a trace section previously marked by a TraceBeginLogEntry.
It includes the total time spent executing the traced block, measured in milliseconds.
Fields:
- Name: the same name provided in the TraceBeginLogEntry.
- DurationMs: the elapsed time between the TraceBeginLogEntry and this entry.
func NewTraceEndLogEntryFromBegin ¶
func NewTraceEndLogEntryFromBegin( begin TraceBeginLogEntry, additionalData ...map[string]any, ) TraceEndLogEntry
NewTraceEndLogEntryFromBegin creates a matching end log entry for a given TraceBeginLogEntry, calculating the total duration of the traced operation in milliseconds.
This function is used to close out a traced block and record how long it took to execute.
Parameters:
- begin (TraceBeginLogEntry): the previously generated trace start entry.
- additionalData (...map[string]any): optional additional metadata.
Returns:
- TraceEndLogEntry: a structured entry marking the end of a traceable operation.
Source Files