Documentation
¶
Overview ¶
Package log provides secure telemetry logging with strict security controls.
SECURITY MODEL:
This package implements strict security controls for telemetry logging to prevent PII and sensitive information from being sent to external telemetry services.
REQUIREMENTS:
- Messages MUST be constant templates only - no dynamic parameter replacement
- Stack traces MUST be redacted to show only Datadog, runtime, and known 3rd party frames
- Errors MUST use SafeError type with message redaction
- slog.Any() only allowed with LogValuer implementations
BENEFITS:
- Constant messages enable deduplication to reduce redundant log transmission
SECURE USAGE PATTERNS:
// ✅ Correct - constant message with structured data
telemetrylog.Error("operation failed", slog.String("operation", "startup"))
telemetrylog.Error("validation error", slog.Any("error", SafeError(err)))
telemetrylog.Error("operation failed", slog.Any("error", SafeError(err)), WithStacktrace())
// ❌ Forbidden - dynamic messages
telemetrylog.Error(err.Error()) // Raw error message
telemetrylog.Error("failed: " + details) // String concatenation
telemetrylog.Error(fmt.Sprintf("error: %s", err)) // Format strings
// ❌ Forbidden - raw error exposure
telemetrylog.Error("failed", slog.Any("error", err)) // Raw error object
telemetrylog.Error("failed", slog.String("err", err.Error())) // Raw error message
Index ¶
- func Debug(message string, attrs ...slog.Attr)
- func Error(message string, attrs ...slog.Attr)
- func LogAndReportError(msg string, err error, opts ...telemetry.LogOption)
- func LogAndReportPanic(msg string, recovered any, opts ...telemetry.LogOption)
- func ReportError(msg string, err error, opts ...telemetry.LogOption)
- func ReportPanic(msg string, recovered any, opts ...telemetry.LogOption)
- func SetDefaultLogger(logger *Logger)
- func Warn(message string, attrs ...slog.Attr)
- type Logger
- type SafeError
- type SafeSlice
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LogAndReportError ¶
LogAndReportError logs msg locally via internal/log.Error and forwards the same constant msg to Error Tracking via ReportError — for call sites that want both a local log line and a report without duplicating the message.
msg MUST be a constant string — see ReportError for the rationale. The format string passed to internal/log.Error is always the percent-escaped msg followed by ": %s" regardless of whether err is nil, so the call site's local dedup key stays stable and a percent in msg is logged verbatim rather than parsed as a format verb.
func LogAndReportPanic ¶
LogAndReportPanic mirrors LogAndReportError for recover() sites, pairing with ReportPanic.
func ReportError ¶
ReportError forwards a constant-message SDK error to telemetry. Call this explicitly at any site that wants its error surfaced in Error Tracking — there is no automatic forwarding from internal/log.Error; a site that doesn't call ReportError simply isn't reported.
msg MUST be a constant string — never the result of fmt.Sprintf, string concatenation, or err.Error(). The constant message is used as a dedup key in telemetry; non-constant values break deduplication and risk leaking PII.
err is scrubbed through NewSafeError before transmission, so only the error type (not the message) is sent to telemetry.
Before telemetry.StartApp runs, reports queue in the global telemetry client's recorder: a 512-entry ring buffer shared by every global telemetry call. When it fills, the oldest queued report is dropped, and the only signal is a single debug-level internal log (off by default). Callers that cannot control startup order should expect an early burst of reports to evict the first ones.
opts may include telemetry.WithTags or additional options. A redacted stack trace is always attached.
func ReportPanic ¶
ReportPanic forwards a recovered panic to telemetry as an error. Call this explicitly at any recover() site that wants the panic surfaced in Error Tracking — see ReportError for why this is opt-in per call site.
msg MUST be a constant string — see ReportError for the rationale.
recovered is the value returned by recover(). If it implements error, it is scrubbed through NewSafeError before transmission. Otherwise (e.g. a panic(string) or a plain struct), only its type is attached — never its content — matching the same disclosure rule NewSafeError applies to errors. A redacted stack trace is always attached.
Before telemetry.StartApp runs, panics queue in the global telemetry client's recorder: a 512-entry ring buffer shared by every global telemetry call. When it fills, the oldest queued report is dropped, and the only signal is a single debug-level internal log (off by default). See ReportError for the caller-facing consequences.
opts may include telemetry.WithTags or additional options.
func SetDefaultLogger ¶ added in v2.4.0
func SetDefaultLogger(logger *Logger)
Types ¶
type SafeError ¶ added in v2.4.0
type SafeError struct {
// contains filtered or unexported fields
}
SafeError represents a sanitized error for secure telemetry logging. It only exposes the error type, never the error message, to prevent PII leakage.
func NewSafeError ¶ added in v2.4.0
NewSafeError creates a SafeError from a regular error
type SafeSlice ¶ added in v2.4.0
type SafeSlice struct {
// contains filtered or unexported fields
}
SafeSlice provides secure logging for slice/array types
func NewSafeSlice ¶ added in v2.4.0
NewSafeSlice creates a SafeSlice from any slice, converting items to strings
func NewSafeSliceWithLimit ¶ added in v2.4.0
NewSafeSliceWithLimit creates a SafeSlice with custom item limit
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package analyzer provides a go/analysis pass that enforces constant first arguments on selected logging functions.
|
Package analyzer provides a go/analysis pass that enforces constant first arguments on selected logging functions. |
|
cmd
command
errlog-vet is a standalone go vet tool bundling the SDK logging safety analyzers: constant message arguments (constantlogmsg), telemetry PII scrubbing (telemetrysafety), and unsafe %v/%+v/%#v format verbs (logformatverbs).
|
errlog-vet is a standalone go vet tool bundling the SDK logging safety analyzers: constant message arguments (constantlogmsg), telemetry PII scrubbing (telemetrysafety), and unsafe %v/%+v/%#v format verbs (logformatverbs). |