logging

Documentation

Overview

Package logging provides structured logging utilities for the mcp-kubernetes application.

This package centralizes logging patterns to ensure consistent, structured logging throughout the codebase using the standard library's slog package.

Key Features

• Structured logging with slog
• PII sanitization (email anonymization, credential masking)
• Host/URL sanitization for security
• Consistent attribute naming across the codebase

Usage Patterns

Create a logger with standard attributes:

logger := logging.WithOperation(slog.Default(), "resource.list")
logger.Info("listing resources",
    logging.Namespace("default"),
    logging.ResourceType("pods"))

Sanitize sensitive data before logging:

logger.Info("user operation",
    logging.UserHash(email),
    logging.SanitizedHost(apiServer))

Security Considerations

This package is designed with security in mind:

• User emails are hashed to prevent PII leakage while allowing correlation
• API server URLs have IP addresses redacted to prevent topology leakage
• Credentials and tokens are never logged directly

Index

• Constants
• func AnonymizeEmail(email string) string
• func Cluster(name string) slog.Attr
• func Domain(email string) slog.Attr
• func Err(err error) slog.Attr
• func ExtractDomain(email string) string
• func Host(host string) slog.Attr
• func Namespace(ns string) slog.Attr
• func Operation(op string) slog.Attr
• func ResourceName(name string) slog.Attr
• func ResourceType(rt string) slog.Attr
• func SanitizeHost(host string) string
• func SanitizeToken(token string) string
• func SanitizedErr(err error) slog.Attr
• func Status(status string) slog.Attr
• func UserHash(email string) slog.Attr
• func WithCluster(logger *slog.Logger, cluster string) *slog.Logger
• func WithOperation(logger *slog.Logger, operation string) *slog.Logger
• func WithTool(logger *slog.Logger, tool string) *slog.Logger
• type Logger
• type SlogAdapter
  • func DefaultLogger() *SlogAdapter
  • func NewSlogAdapter(logger *slog.Logger) *SlogAdapter
  • func (a *SlogAdapter) Debug(msg string, args ...interface{})
  • func (a *SlogAdapter) Error(msg string, args ...interface{})
  • func (a *SlogAdapter) Info(msg string, args ...interface{})
  • func (a *SlogAdapter) Logger() *slog.Logger
  • func (a *SlogAdapter) Warn(msg string, args ...interface{})

Constants

const (
	KeyOperation    = "operation"
	KeyNamespace    = "namespace"
	KeyResourceType = "resource_type"
	KeyResourceName = "resource_name"
	KeyCluster      = "cluster"
	KeyUserHash     = "user_hash"
	KeyDuration     = "duration"
	KeyStatus       = "status"
	KeyError        = "error"
	KeyHost         = "host"
	KeyTool         = "tool"
)

Common log attribute keys for consistent naming across the codebase.

const (
	StatusSuccess = "success"
	StatusError   = "error"
)

Status values for consistent logging.

Functions

func AnonymizeEmail

func AnonymizeEmail(email string) string

AnonymizeEmail returns a hashed representation of an email for logging purposes. This allows correlation of log entries without exposing PII.

func Cluster

func Cluster(name string) slog.Attr

Cluster returns a slog attribute for the cluster name.

func Domain

func Domain(email string) slog.Attr

Domain returns a slog attribute for the email domain (lower cardinality than full email).

func Err

func Err(err error) slog.Attr

Err returns a slog attribute for an error.

func ExtractDomain

func ExtractDomain(email string) string

ExtractDomain extracts the domain part from an email address. This is useful for lower-cardinality logging where the full email would create too many unique values.

func Host

func Host(host string) slog.Attr

Host returns a slog attribute for a host with IP addresses sanitized.

func Namespace

func Namespace(ns string) slog.Attr

Namespace returns a slog attribute for the namespace.

func Operation

func Operation(op string) slog.Attr

Operation returns a slog attribute for the operation name.

func ResourceName

func ResourceName(name string) slog.Attr

ResourceName returns a slog attribute for the resource name.

func ResourceType

func ResourceType(rt string) slog.Attr

ResourceType returns a slog attribute for the resource type.

func SanitizeHost

func SanitizeHost(host string) string

SanitizeHost returns a sanitized version of the host for logging purposes. This function redacts IP addresses (both IPv4 and IPv6) to prevent sensitive network topology information from appearing in logs, while preserving enough context for debugging.

Examples:

• "https://192.168.1.100:6443" -> "https://<redacted-ip>:6443"
• "https://api.cluster.example.com:6443" -> "https://api.cluster.example.com:6443"
• "192.168.1.100" -> "<redacted-ip>"
• "https://[2001:db8::1]:6443" -> "https://<redacted-ip>:6443"
• "2001:db8::1" -> "<redacted-ip>"
• "" -> "<empty>"

func SanitizeToken

func SanitizeToken(token string) string

SanitizeToken returns a masked version of a token for logging. It returns a length indicator without exposing any token content, as even partial token prefixes (like JWT headers) can aid attacks.

func SanitizedErr

func SanitizedErr(err error) slog.Attr

SanitizedErr returns a slog attribute for an error with IP addresses redacted. This should be used when logging errors that may contain hostnames or IP addresses from Kubernetes API server responses, which could leak network topology information.

func Status

func Status(status string) slog.Attr

Status returns a slog attribute for the status.

func UserHash

func UserHash(email string) slog.Attr

UserHash returns a slog attribute with the anonymized user email. This is a convenience function to reduce repetition in logging calls and ensure consistent attribute naming across the codebase.

Usage:

logger.Info("operation completed", logging.UserHash(user.Email))

func WithCluster

func WithCluster(logger *slog.Logger, cluster string) *slog.Logger

WithCluster returns a logger with the cluster attribute set.

func WithOperation

func WithOperation(logger *slog.Logger, operation string) *slog.Logger

WithOperation returns a logger with the operation attribute set.

func WithTool

func WithTool(logger *slog.Logger, tool string) *slog.Logger

WithTool returns a logger with the tool attribute set.

Types

type Logger

type Logger interface {
	Debug(msg string, args ...interface{})
	Info(msg string, args ...interface{})
	Warn(msg string, args ...interface{})
	Error(msg string, args ...interface{})
}

Logger is the canonical interface for structured logging throughout the application. It provides a simple, level-based logging API compatible with slog. The k8s package imports this interface via a type alias for backward compatibility.

type SlogAdapter

type SlogAdapter struct {
	// contains filtered or unexported fields
}

SlogAdapter adapts an slog.Logger to the Logger interface. This allows slog to be used with code that expects the simpler Logger interface.

func DefaultLogger

func DefaultLogger() *SlogAdapter

DefaultLogger returns a Logger using the default slog.Logger.

func NewSlogAdapter

func NewSlogAdapter(logger *slog.Logger) *SlogAdapter

NewSlogAdapter creates a new SlogAdapter wrapping the given slog.Logger. If logger is nil, slog.Default() is used.

func (*SlogAdapter) Debug

func (a *SlogAdapter) Debug(msg string, args ...interface{})

Debug logs a debug message with key-value pairs. Arguments should be provided as alternating key-value pairs: key1, value1, key2, value2, ...

func (*SlogAdapter) Error

func (a *SlogAdapter) Error(msg string, args ...interface{})

Error logs an error message with key-value pairs. Arguments should be provided as alternating key-value pairs: key1, value1, key2, value2, ...

func (*SlogAdapter) Info

func (a *SlogAdapter) Info(msg string, args ...interface{})

Info logs an info message with key-value pairs. Arguments should be provided as alternating key-value pairs: key1, value1, key2, value2, ...

func (*SlogAdapter) Logger

func (a *SlogAdapter) Logger() *slog.Logger

Logger returns the underlying slog.Logger for direct access when needed.

func (*SlogAdapter) Warn

func (a *SlogAdapter) Warn(msg string, args ...interface{})

Warn logs a warning message with key-value pairs. Arguments should be provided as alternating key-value pairs: key1, value1, key2, value2, ...