Documentation
¶
Overview ¶
Package analyzer provides a go/analysis pass that enforces constant first arguments on selected logging functions.
Protected functions (configurable via New):
- github.com/DataDog/dd-trace-go/v2/internal/log.Error
- github.com/DataDog/dd-trace-go/v2/internal/log.Warn
- github.com/DataDog/dd-trace-go/v2/internal/telemetry/log.Debug
- github.com/DataDog/dd-trace-go/v2/internal/telemetry/log.Warn
- github.com/DataDog/dd-trace-go/v2/internal/telemetry/log.Error
- github.com/DataDog/dd-trace-go/v2/internal/telemetry/log.(*Logger).Debug
- github.com/DataDog/dd-trace-go/v2/internal/telemetry/log.(*Logger).Warn
- github.com/DataDog/dd-trace-go/v2/internal/telemetry/log.(*Logger).Error
- github.com/DataDog/dd-trace-go/v2/internal/telemetry/log.ReportError
- github.com/DataDog/dd-trace-go/v2/internal/telemetry/log.ReportPanic
- github.com/DataDog/dd-trace-go/v2/internal/telemetry/log.LogAndReportError
- github.com/DataDog/dd-trace-go/v2/internal/telemetry/log.LogAndReportPanic
The internal/log entries and the internal/telemetry/log entries are checked for different reasons: internal/log.Error/Warn never reach telemetry — the constant-message requirement there only protects internal/log's own local rate-limiting/aggregation dedup key. The internal/telemetry/log entries (including ReportError/ReportPanic and their LogAndReport* counterparts, the only ways an SDK error reaches Error Tracking — there is no automatic forwarding from internal/log) additionally use the constant message as telemetry's own dedup key, where a non-constant value also risks leaking PII.
Because the package-level functions (Debug/Warn/Error) and their Logger method counterparts share the same name and package path, a single FuncSpec per name covers both call styles.
The analyzer intentionally skips the internal/telemetry/log package itself (see DefaultSkipPkgs) to avoid false positives on internal delegation calls like:
func Error(message string, ...) { defaultLogger.Load().Error(message, ...) }
This check is equivalent to the telemetryLogConstantMessage ruleguard rule in rules/telemetry_rules.go, extended to cover internal/log and the helpers ReportError/ReportPanic. The goal is to allow dropping the ruleguard rule once the analyzer is wired into all CI paths.
formatverbs.go replaces the ruleguard rules formerly in rules/logging_rules.go (internalLogFormatVerbs, stdLogFormatVerbs, and their err.Error() suggestion counterparts), which required golangci-lint's gocritic/ruleguard integration.
telemetrysafety.go replaces the ruleguard rules formerly in rules/telemetry_rules.go (telemetryLogSmartSlogAny, telemetryLogStringErrorCall, telemetryLogRawErrorUsage), which required golangci-lint's gocritic/ruleguard integration. Folding them into this go/analysis pass means the SDK's own error-reporting API (this package) is checked by the same standalone `make lint/errlog` tool as the constant-message rule, with one less moving part in CI.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Analyzer = New(DefaultFuncs, DefaultSkipPkgs...)
Analyzer is the production analyzer configured with DefaultFuncs and DefaultSkipPkgs.
var DefaultFuncs = []FuncSpec{
{PkgPath: "github.com/DataDog/dd-trace-go/v2/internal/log", FuncName: "Error", MsgArgIndex: 0},
{PkgPath: "github.com/DataDog/dd-trace-go/v2/internal/log", FuncName: "Warn", MsgArgIndex: 0},
{PkgPath: telemetryLogPkg, FuncName: "Debug", MsgArgIndex: 0},
{PkgPath: telemetryLogPkg, FuncName: "Warn", MsgArgIndex: 0},
{PkgPath: telemetryLogPkg, FuncName: "Error", MsgArgIndex: 0},
{PkgPath: telemetryLogPkg, FuncName: "ReportError", MsgArgIndex: 0},
{PkgPath: telemetryLogPkg, FuncName: "ReportPanic", MsgArgIndex: 0},
{PkgPath: telemetryLogPkg, FuncName: "LogAndReportError", MsgArgIndex: 0},
{PkgPath: telemetryLogPkg, FuncName: "LogAndReportPanic", MsgArgIndex: 0},
}
DefaultFuncs is the set of functions checked by the default Analyzer.
The telemetry/log package entries (Debug/Warn/Error) cover both package-level calls and Logger method calls — resolveFunc maps both to the same (pkg, name) key via pass.TypesInfo.Uses.
var DefaultSkipPkgs = []string{
telemetryLogPkg,
"github.com/DataDog/dd-trace-go/v2/instrumentation",
}
DefaultSkipPkgs is the set of package paths skipped by the default Analyzer.
The telemetry/log package is skipped because its own implementation delegates through the same function names with a variable message parameter:
func Error(message string, ...) { defaultLogger.Load().Error(message, ...) }
instrumentation is skipped for the same reason: instrumentation.Logger's Debug/Info/Warn/Error methods are thin pass-throughs that forward whatever message their caller supplies to log.Debug/Warn/Error — the constant-message contract is enforced at the call sites of instrumentation.Logger, not here.
Flagging either would be a false positive; enforcement happens at call sites.
var FormatVerbsAnalyzer = NewFormatVerbs("github.com/DataDog/dd-trace-go/v2/internal/log")
FormatVerbsAnalyzer is the production analyzer, scoped to internal/log and, in allow-listed files, the standard library log package.
var TelemetrySafetyAnalyzer = NewTelemetrySafety(telemetryLogPkg, telemetryLogPkg)
TelemetrySafetyAnalyzer is the production analyzer, scoped to internal/telemetry/log; it skips that package's own files (see New's doc).
Functions ¶
func New ¶
New returns an analysis.Analyzer configured with the given function specs. skipPkgs lists package import paths whose files are not checked; use this to suppress false positives in packages that internally delegate through the protected function names (e.g. the telemetry/log implementation itself).
Use New to build a test-scoped analyzer with fake package paths.
func NewFormatVerbs ¶
NewFormatVerbs returns an analyzer checking internalLogPkg's Debug/Info/Warn/Error calls (and, in stdLogAllowedFile files, the standard "log" package's Printf/Fatalf/Panicf) for unsafe %v/%+v/%#v usage. Test files are skipped, matching the retired ruleguard rules' own scope.
func NewTelemetrySafety ¶
NewTelemetrySafety returns an analyzer that checks slog.Any/slog.String arguments passed directly to logPkg's Debug/Warn/Error functions and Logger methods. skipPkg's own files are not analyzed — internal/telemetry/log's implementation builds these slog.Attr values itself (e.g. forward.go, helpers.go) using NewSafeError directly rather than through logPkg's public entry points, so there is nothing for this analyzer to see there, but the skip keeps the intent explicit and matches Analyzer's convention.
Types ¶
type FuncSpec ¶
type FuncSpec struct {
// PkgPath is the full import path of the package, e.g.
// "github.com/DataDog/dd-trace-go/v2/internal/log".
PkgPath string
// FuncName is the unqualified function name, e.g. "Error".
FuncName string
// MsgArgIndex is the zero-based index of the message argument.
MsgArgIndex int
}
FuncSpec identifies a function and which argument index holds the constant message.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
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). |