chore: deprecate cloudzap package and zap-based logging API

[fredrikaverpil]

Why?

The cloudslog.Handler configured by cloudrunner.Run provides the same capabilities as the cloudzap package — Cloud Logging field formatting, error reporting, and trace correlation — using standard log/slog instead of go.uber.org/zap. The zap logger, its context middleware, and explicit trace field injection are all redundant now.

Rather than removing the zap path outright (as in #814), this deprecates it first to give consumers time to migrate to log/slog with cloudslog.

What?

• Deprecate the cloudzap package and all its exported symbols
• Deprecate cloudrunner.Logger and cloudrunner.WithLoggerFields
• Deprecate cloudrequestlog.ErrorDetails (returns zap.Field)
• Deprecate WithOtelTraceHook, TraceIDHook, IDHook
• Deprecate ProjectID and TraceHook fields on both cloudotel.TraceMiddleware and cloudtrace.Middleware
• Fix incorrect doc comment on WithOtelTraceHook (said WithTraceHook)

Migration guide

Logging

Replace cloudrunner.Logger(ctx) with standard log/slog context functions. Custom fields can be passed directly as arguments:

// Before
cloudrunner.Logger(ctx).Info("processing event", zap.String("event_id", id))

// After
slog.InfoContext(ctx, "processing event", slog.String("event_id", id))

Context enrichment

Both cloudrunner.WithLoggerFields and cloudslog.With enrich all subsequent logs within the returned context. The replacement is a direct swap:

// Before
ctx = cloudrunner.WithLoggerFields(ctx,
    zap.String("event_type", eventType),
    zap.String("event_id", id),
)

// After
ctx = cloudslog.With(ctx,
    slog.String("event_type", eventType),
    slog.String("event_id", id),
)

Trace correlation

No action needed. The cloudslog.Handler (configured by cloudrunner.Run) automatically extracts trace/span IDs from the OpenTelemetry span context on every log call. Remove any WithOtelTraceHook or WithTraceHook options from your cloudrunner.Run call — they are no longer needed.

Error helpers

Use cloudslog.Errors for logging multiple errors:

slog.WarnContext(ctx, "partial failure", cloudslog.Errors(errs))

Request logging (cloudrequestlog)

The cloudrequestlog package already uses slog internally and is not deprecated. However, cloudrequestlog.ErrorDetails returns a zap.Field and is now deprecated. AdditionalFields.Add still accepts both zap.Field and slog.Attr for backwards compatibility, but prefer slog.Attr when adding custom fields to request logs.

Notes

• No behavioral changes — existing code continues to work
• Follow-up: remove the deprecated code in a future major version (see feat!: remove cloudzap #814)

[alethenorio]

Cloudrunner-go sets its own default with Google Cloud Logging support so using slog.SetDefault is probably not what one wants to do (generally)

[fredrikaverpil]

I updated it to

// WithLogger adds a logger to the current context.
//
// Deprecated: cloudrunner.Run configures the default slog logger with cloudslog.Handler.
// Use slog.InfoContext, slog.WarnContext, etc. instead of a context-based zap logger.
func WithLogger(ctx context.Context, logger *zap.Logger) context.Context {
	return context.WithValue(ctx, loggerContextKey{}, logger)
}

[alethenorio]

This is actually not used and was mistakenly missed to be deleted in the last PR.

[fredrikaverpil]

Ok. I guess we shouldn't remove it- or do you think we should?

I changed it now into

// ProjectID of the project the service is running in.
//
// Deprecated: No longer used. As per https://docs.cloud.google.com/trace/docs/trace-log-integration
// the preferred trace format is now just the trace ID, not projects/PROJECT_ID/traces/TRACE_ID.
ProjectID string

[alethenorio]

There is actually no equivalent function at the moment. I did a quick search internally and I don't believe anybody is using this so let's just make the message clearer.

[fredrikaverpil]

Good catch, changed it:

// ErrorDetails creates a zap.Field that logs the gRPC error details of the provided error.
//
// Deprecated: Returns a zap.Field which ties consumers to the deprecated zap dependency.
// There is no drop-in slog replacement yet. This function will be removed in a future version.
func ErrorDetails(err error) zap.Field {
  ...
}

[alethenorio]

This is actually not used and was mistakenly missed to be removed from last PR

[fredrikaverpil]

Changed it like in the previous instance:

// ProjectID of the project the service is running in.
//
// Deprecated: No longer used. As per https://docs.cloud.google.com/trace/docs/trace-log-integration
// the preferred trace format is now just the trace ID, not projects/PROJECT_ID/traces/TRACE_ID.
ProjectID string

[alethenorio]

WithOtelTraceHook allows selecting the new opentelemetry trace features (instead of the old custom one). The reason it should be deprecated is that we will remove the old features completely and there will be no reason to select the one since it will be the only one. (I feel the comment was already correct in this one which was already marked as deprecated except for the function name which was wrong)

[fredrikaverpil]

Makes sense, I reverted this change into the deprecation warning we already had.