[Proposal] Standardized Logging for Policy Developers

[renuka-fernando]

Summary

Provide a standardized logging mechanism for policy developers by injecting a pre-configured *slog.Logger into the policy factory function. This ensures consistent log formatting across all policies, automatic policy identification in logs, and simplifies the developer experience.

Motivation

Problem Statement

Currently, policies use Go's log/slog directly with manual conventions:

• Policy developers manually add policy name as a string prefix (e.g., "JWT Auth Policy: ...")
• Format varies between policies - no consistency
• Policy name is not a structured field, making logs harder to filter/search in log aggregators
• Developers can mistype or forget to include the policy name
• No standard way to include request correlation IDs

Example of current inconsistent logging:

slog.Debug("JWT Auth Policy: Token validation started", "path", ctx.Path)
slog.Debug("API Key Auth Policy: OnRequest started", "apiId", ctx.APIId)
slog.Warn("Rate limit exceeded")  // Missing policy identifier

Who Benefits

• Policy Developers: Simpler API - just use the provided logger, no need to configure or remember conventions
• Platform Operators: Consistent, filterable logs across all policies with structured policy and requestId fields
• Support Engineers: Easier debugging with reliable policy identification and request correlation

Why Now

• Multiple policies are being developed with inconsistent logging patterns
• As the policy ecosystem grows, standardization becomes harder to retrofit
• Current policies need updates anyway, making this a good time for breaking changes

Detailed Design

Overview

The policy engine will create a pre-configured *slog.Logger with the policy name as a structured field and pass it to the policy factory function. An SDK helper function WithRequestID() will allow policies to enrich logs with request correlation IDs during request/response processing. This approach requires no changes to PolicyMetadata and keeps the logger creation logic centralized in the policy engine.

Changes Required

Component	File/Area	Change Description
SDK	sdk/gateway/policy/v1alpha/interface.go	Update PolicyFactory signature to add logger *slog.Logger parameter
SDK	sdk/gateway/policy/v1alpha/logger.go	Add new file with WithRequestID() helper function
Policy Engine	gateway/policy-engine/internal/registry/registry.go	Create logger with policy name and pass to factory
All Policies	gateway/policies/*/	Update GetPolicy signature and use provided logger

API Changes

N/A - No REST API changes.

Configuration Changes

N/A - No configuration changes.

Examples

Before:

package mypolicy

import "log/slog"

type MyPolicy struct {
    // No logger field
}

func GetPolicy(
    metadata policy.PolicyMetadata,
    params map[string]interface{},
) (policy.Policy, error) {
    slog.Debug("My Policy: Initializing", "param", params["key"])
    return &MyPolicy{}, nil
}

func (p *MyPolicy) OnRequest(ctx *policy.RequestContext, params map[string]interface{}) policy.RequestAction {
    slog.Debug("My Policy: Processing request", "path", ctx.Path, "requestId", ctx.RequestID)
    return policy.RequestAction{}
}

After:

package mypolicy

import (
    "log/slog"
    policy "github.com/wso2/api-platform/sdk/gateway/policy/v1alpha"
)

type MyPolicy struct {
    logger *slog.Logger
}

func GetPolicy(
    metadata policy.PolicyMetadata,
    params map[string]interface{},
    logger *slog.Logger,
) (policy.Policy, error) {
    logger.Debug("Initializing", "param", params["key"])
    return &MyPolicy{logger: logger}, nil
}

func (p *MyPolicy) OnRequest(ctx *policy.RequestContext, params map[string]interface{}) policy.RequestAction {
    log := policy.WithRequestID(p.logger, ctx.RequestID)
    log.Debug("Processing request", "path", ctx.Path)
    return policy.RequestAction{}
}

Log Output (Text format):

level=DEBUG policy=my-policy msg=Initializing param=value
level=DEBUG policy=my-policy requestId=abc-123 msg="Processing request" path=/pets

Log Output (JSON format):

{"level":"DEBUG","policy":"my-policy","msg":"Initializing","param":"value"}
{"level":"DEBUG","policy":"my-policy","requestId":"abc-123","msg":"Processing request","path":"/pets"}

Drawbacks

• Breaking Change: All existing policies must update their GetPolicy function signature
• Migration Effort: Every policy needs to be updated, though the changes are mechanical

Alternatives Considered

Alternative 1: SDK Logger Utility Function

• Description: Provide policy.NewLogger(metadata, policyName, policyVersion) that policies call to create their own logger
• Pros: No change to factory signature; opt-in adoption
• Cons: Policy developers must remember to call it; can pass wrong policy name; extra boilerplate
• Rejection Reason: Error-prone - developers can forget or mistype the policy name

Alternative 2: Logger in PolicyMetadata

• Description: Add Logger *slog.Logger field to PolicyMetadata struct
• Pros: No signature change; logger is "just there" in metadata
• Cons: Mixes concerns - metadata is data, logger is a tool; less explicit
• Rejection Reason: Less idiomatic Go; obscures that a logger is being provided

Alternative 3: No Change - Document Convention

• Description: Keep current approach, document the recommended logging convention
• Pros: No code changes; no breaking changes
• Cons: Relies on developers following conventions; no enforcement; inconsistent logs persist
• Rejection Reason: Does not solve the core problem of inconsistency and manual error

Compatibility

Question	Answer	Details
Backwards compatible?	No	PolicyFactory signature changes
Requires migration?	Yes	All policies must update GetPolicy signature
Breaking changes?	Yes	PolicyFactory function signature adds logger parameter

Migration Steps

1. Update SDK with new PolicyFactory signature and WithRequestID() helper
2. Update policy engine registry to create and pass logger
3. Update each policy's GetPolicy function to accept logger *slog.Logger
4. Replace manual slog.Debug("Policy Name: ...") calls with logger.Debug("...")
5. Use policy.WithRequestID(logger, ctx.RequestID) for request-scoped logging
6. Run tests to verify all policies compile and function correctly

Definition of Done

• PolicyFactory signature updated in SDK
• WithRequestID() helper added to SDK
• Policy engine registry creates and passes logger to factories
• All existing policies updated to new signature
• All existing policies use provided logger instead of direct slog calls
• Unit tests pass for all updated policies
• Integration tests verify logs contain policy field
• Documentation updated

References

• Go slog package - Standard library structured logging