Rename request ID to correlation ID

Author: adutra

CHANGELOG.md

@@ -43,6 +43,10 @@ request adding CHANGELOG notes for breaking (!) changes and possibly other secti
 
 ### Deprecations
 
+* The property `polaris.log.request-id-header-name` is deprecated and has been renamed to
+  `polaris.correlation-id.header-name`; the old name is still supported for backwards compatibility, 
+  but will generate a warning.
+
 ### Fixes
 
 ### Commits

helm/polaris/README.md

@@ -214,6 +214,9 @@ ct install --namespace polaris --charts ./helm/polaris
 | configMapLabels | object | `{}` | Additional Labels to apply to polaris configmap. |
 | containerSecurityContext | object | `{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"runAsNonRoot":true,"runAsUser":10000,"seccompProfile":{"type":"RuntimeDefault"}}` | Security context for the polaris container. See https://kubernetes.io/docs/tasks/configure-pod-container/security-context/. |
 | containerSecurityContext.runAsUser | int | `10000` | UID 10000 is compatible with Polaris OSS default images; change this if you are using a different image. |
+| correlationId | object | `{"generator":{"type":"default"},"headerName":"Polaris-Request-Id"}` | Configuration for correlation IDs. |
+| correlationId.generator.type | string | `"default"` | The type of the correlation ID generator to use. |
+| correlationId.headerName | string | `"Polaris-Request-Id"` | The name of the header that contains the correlation ID. If a request does not contain this header, it will be assigned a new correlation ID generated using the configured generator. All responses will include the correlation ID in this header. |
 | cors | object | `{"accessControlAllowCredentials":null,"accessControlMaxAge":null,"allowedHeaders":[],"allowedMethods":[],"allowedOrigins":[],"exposedHeaders":[]}` | Polaris CORS configuration. |
 | cors.accessControlAllowCredentials | string | `nil` | The `Access-Control-Allow-Credentials` response header. The value of this header will default to `true` if `allowedOrigins` property is set and there is a match with the precise `Origin` header. |
 | cors.accessControlMaxAge | string | `nil` | The `Access-Control-Max-Age` response header value indicating how long the results of a pre-flight request can be cached. Must be a valid duration. |
@@ -247,7 +250,7 @@ ct install --namespace polaris --charts ./helm/polaris
 | livenessProbe.successThreshold | int | `1` | Minimum consecutive successes for the probe to be considered successful after having failed. Minimum value is 1. |
 | livenessProbe.terminationGracePeriodSeconds | int | `30` | Optional duration in seconds the pod needs to terminate gracefully upon probe failure. Minimum value is 1. |
 | livenessProbe.timeoutSeconds | int | `10` | Number of seconds after which the probe times out. Minimum value is 1. |
-| logging | object | `{"categories":{"org.apache.iceberg.rest":"INFO","org.apache.polaris":"INFO"},"console":{"enabled":true,"format":"%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] [%X{requestId},%X{realmId}] [%X{traceId},%X{parentId},%X{spanId},%X{sampled}] (%t) %s%e%n","json":false,"threshold":"ALL"},"file":{"enabled":false,"fileName":"polaris.log","format":"%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] [%X{requestId},%X{realmId}] [%X{traceId},%X{parentId},%X{spanId},%X{sampled}] (%t) %s%e%n","json":false,"logsDir":"/deployments/logs","rotation":{"fileSuffix":null,"maxBackupIndex":5,"maxFileSize":"100Mi"},"storage":{"className":"standard","selectorLabels":{},"size":"512Gi"},"threshold":"ALL"},"level":"INFO","mdc":{},"requestIdHeaderName":"Polaris-Request-Id"}` | Logging configuration. |
+| logging | object | `{"categories":{"org.apache.iceberg.rest":"INFO","org.apache.polaris":"INFO"},"console":{"enabled":true,"format":"%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] [%X{requestId},%X{realmId}] [%X{traceId},%X{parentId},%X{spanId},%X{sampled}] (%t) %s%e%n","json":false,"threshold":"ALL"},"file":{"enabled":false,"fileName":"polaris.log","format":"%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] [%X{requestId},%X{realmId}] [%X{traceId},%X{parentId},%X{spanId},%X{sampled}] (%t) %s%e%n","json":false,"logsDir":"/deployments/logs","rotation":{"fileSuffix":null,"maxBackupIndex":5,"maxFileSize":"100Mi"},"storage":{"className":"standard","selectorLabels":{},"size":"512Gi"},"threshold":"ALL"},"level":"INFO","mdc":{}}` | Logging configuration. |
 | logging.categories | object | `{"org.apache.iceberg.rest":"INFO","org.apache.polaris":"INFO"}` | Configuration for specific log categories. |
 | logging.console | object | `{"enabled":true,"format":"%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] [%X{requestId},%X{realmId}] [%X{traceId},%X{parentId},%X{spanId},%X{sampled}] (%t) %s%e%n","json":false,"threshold":"ALL"}` | Configuration for the console appender. |
 | logging.console.enabled | bool | `true` | Whether to enable the console appender. |
@@ -271,7 +274,6 @@ ct install --namespace polaris --charts ./helm/polaris
 | logging.file.threshold | string | `"ALL"` | The log level of the file appender. |
 | logging.level | string | `"INFO"` | The log level of the root category, which is used as the default log level for all categories. |
 | logging.mdc | object | `{}` | Configuration for MDC (Mapped Diagnostic Context). Values specified here will be added to the log context of all incoming requests and can be used in log patterns. |
-| logging.requestIdHeaderName | string | `"Polaris-Request-Id"` | The header name to use for the request ID. |
 | managementService | object | `{"annotations":{},"clusterIP":"None","externalTrafficPolicy":null,"internalTrafficPolicy":null,"ports":[{"name":"polaris-mgmt","nodePort":null,"port":8182,"protocol":null,"targetPort":null}],"sessionAffinity":null,"trafficDistribution":null,"type":"ClusterIP"}` | Management service settings. These settings are used to configure liveness and readiness probes, and to configure the dedicated headless service that will expose health checks and metrics, e.g. for metrics scraping and service monitoring. |
 | managementService.annotations | object | `{}` | Annotations to add to the service. |
 | managementService.clusterIP | string | `"None"` | By default, the management service is headless, i.e. it does not have a cluster IP. This is generally the right option for exposing health checks and metrics, e.g. for metrics scraping and service monitoring. |

helm/polaris/templates/configmap.yaml

@@ -165,7 +165,6 @@ data:
     {{- range $k, $v := $categories -}}
     {{- $_ = set $map (printf "quarkus.log.category.\"%s\".level" $k) $v -}}
     {{- end -}}
-    {{- $_ = set $map "polaris.log.request-id-header-name" .Values.logging.requestIdHeaderName -}}
     {{- $mdc := dict -}}
     {{- list .Values.logging.mdc "" $mdc | include "polaris.mergeConfigTree" -}}
     {{- range $k, $v := $mdc -}}
@@ -208,6 +207,10 @@ data:
     {{- $_ = set $map "quarkus.micrometer.enabled" "false" -}}
     {{- end -}}
 
+    {{- /* Correlation ID */ -}}
+    {{- $_ = set $map "polaris.correlation-id.header-name" .Values.correlationId.headerName -}}
+    {{- $_ = set $map "polaris.correlation-id.generator.type" .Values.correlationId.generator.type -}}
+
     {{- /* Advanced Configuration (must be done last since it can override any of the settings above) */ -}}
     {{- list .Values.advancedConfig "" $map | include "polaris.mergeConfigTree" -}}
 

helm/polaris/values.yaml

@@ -442,8 +442,6 @@ serviceMonitor:
 logging:
   # -- The log level of the root category, which is used as the default log level for all categories.
   level: INFO
-  # -- The header name to use for the request ID.
-  requestIdHeaderName: Polaris-Request-Id
   # -- Configuration for the console appender.
   console:
     # -- Whether to enable the console appender.
@@ -518,6 +516,16 @@ realmContext:
   realms:
     - POLARIS
 
+# -- Configuration for correlation IDs.
+correlationId:
+  # -- The name of the header that contains the correlation ID.
+  # If a request does not contain this header, it will be assigned a new correlation ID generated
+  # using the configured generator. All responses will include the correlation ID in this header.
+  headerName: Polaris-Request-Id
+  generator:
+    # -- The type of the correlation ID generator to use.
+    type: default
+
 # -- Polaris features configuration.
 features:
   # -- Features to enable or disable globally. If a feature is not present in the map, the default

runtime/defaults/src/main/resources/application.properties

@@ -89,7 +89,8 @@ quarkus.oidc.tenant-enabled=false
 # quarkus.oidc.idp1.auth-server-url=https://auth.example.com/realms/polaris2
 # quarkus.oidc.idp1.client-id=polaris2
 
-# quarkus.otel.sdk.disabled is set to `true` by default to avoid spuriour errors about
+# OpenTelemetry settings.
+# quarkus.otel.sdk.disabled is set to `true` by default to avoid spurious errors about
 # trace collector connections being impossible to establish. This setting can be enabled
 # at runtime after configuring other OTel properties for proper trace data collection.
 quarkus.otel.sdk.disabled=true
@@ -106,6 +107,9 @@ quarkus.fault-tolerance.global.timeout.enabled=false
 # quarkus.fault-tolerance.global.timeout.unit=minutes
 # quarkus.fault-tolerance.global.timeout.value=10
 
+polaris.correlation-id.header-name=Polaris-Request-Id
+polaris.correlation-id.generator.type=default
+
 polaris.realm-context.type=default
 polaris.realm-context.realms=POLARIS
 polaris.realm-context.header-name=Polaris-Realm
@@ -146,7 +150,6 @@ polaris.event-listener.type=no-op
 # polaris.event-listener.aws-cloudwatch.region=us-east-1
 # polaris.event-listener.aws-cloudwatch.synchronous-mode=false
 
-polaris.log.request-id-header-name=Polaris-Request-Id
 # polaris.log.mdc.aid=polaris
 # polaris.log.mdc.sid=polaris-service
 

runtime/service/src/main/java/org/apache/polaris/service/config/ConfigRelocationInterceptor.java

@@ -0,0 +1,42 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.polaris.service.config;
+
+import io.smallrye.config.RelocateConfigSourceInterceptor;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class ConfigRelocationInterceptor extends RelocateConfigSourceInterceptor {
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(ConfigRelocationInterceptor.class);
+
+  public ConfigRelocationInterceptor() {
+    super(ConfigRelocationInterceptor::applyRelocations);
+  }
+
+  private static String applyRelocations(String name) {
+    if (name.equals("polaris.log.request-id-header-name")) {
+      String replacement = "polaris.correlation-id.header-name";
+      LOGGER.warn("Property '{}' is deprecated, use '{}' instead", name, replacement);
+      return replacement;
+    }
+    return name;
+  }
+}

runtime/service/src/main/java/org/apache/polaris/service/config/FilterPriorities.java

@@ -21,8 +21,8 @@
 import jakarta.ws.rs.Priorities;
 
 public final class FilterPriorities {
-  public static final int REQUEST_ID_FILTER = Priorities.AUTHENTICATION - 101;
-  public static final int REALM_CONTEXT_FILTER = REQUEST_ID_FILTER + 1;
+  public static final int CORRELATION_ID_FILTER = Priorities.AUTHENTICATION - 101;
+  public static final int REALM_CONTEXT_FILTER = CORRELATION_ID_FILTER + 1;
   public static final int RATE_LIMITER_FILTER = Priorities.USER;
   public static final int MDC_FILTER = REALM_CONTEXT_FILTER + 1;
   public static final int TRACING_FILTER = REALM_CONTEXT_FILTER + 2;

runtime/service/src/main/java/org/apache/polaris/service/config/ServiceProducers.java

@@ -71,6 +71,8 @@
 import org.apache.polaris.service.context.RealmContextConfiguration;
 import org.apache.polaris.service.context.RealmContextFilter;
 import org.apache.polaris.service.context.RealmContextResolver;
+import org.apache.polaris.service.correlation.CorrelationIdConfiguration;
+import org.apache.polaris.service.correlation.CorrelationIdGenerator;
 import org.apache.polaris.service.credentials.PolarisCredentialManagerConfiguration;
 import org.apache.polaris.service.events.PolarisEventListenerConfiguration;
 import org.apache.polaris.service.events.listeners.PolarisEventListener;
@@ -402,6 +404,14 @@ public PolarisCredentialManager polarisCredentialManager(
     return credentialManagers.select(Identifier.Literal.of(config.type())).get();
   }
 
+  @Produces
+  @ApplicationScoped
+  public CorrelationIdGenerator correlationIdGenerator(
+      CorrelationIdConfiguration config,
+      @Any Instance<CorrelationIdGenerator> correlationIdGenerators) {
+    return correlationIdGenerators.select(Identifier.Literal.of(config.generator().type())).get();
+  }
+
   public void closeTaskExecutor(@Disposes @Identifier("task-executor") ManagedExecutor executor) {
     executor.close();
   }

runtime/service/src/main/java/org/apache/polaris/service/correlation/CorrelationIdConfiguration.java

@@ -0,0 +1,49 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.polaris.service.correlation;
+
+import io.smallrye.config.ConfigMapping;
+
+@ConfigMapping(prefix = "polaris.correlation-id")
+public interface CorrelationIdConfiguration {
+
+  /**
+   * The name of the header that contains the correlation ID.
+   *
+   * <p>If a request does not contain this header, it will be assigned a new correlation ID
+   * generated using the configured {@link #generator()}.
+   *
+   * <p>All responses will include the correlation ID in this header.
+   */
+  String headerName();
+
+  /**
+   * The correlation ID generator to use, when a request does not contain the {@link #headerName()}.
+   */
+  Generator generator();
+
+  interface Generator {
+
+    /**
+     * The type of the correlation ID generator. Must be a registered {@link CorrelationIdGenerator}
+     * identifier.
+     */
+    String type();
+  }
+}

runtime/service/src/main/java/org/apache/polaris/service/tracing/RequestIdFilter.java renamed to runtime/service/src/main/java/org/apache/polaris/service/correlation/CorrelationIdFilter.java

@@ -16,7 +16,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.apache.polaris.service.tracing;
+package org.apache.polaris.service.correlation;
 
 import io.smallrye.mutiny.Uni;
 import jakarta.inject.Inject;
@@ -26,39 +26,38 @@
 import jakarta.ws.rs.core.Response;
 import org.apache.iceberg.rest.responses.ErrorResponse;
 import org.apache.polaris.service.config.FilterPriorities;
-import org.apache.polaris.service.logging.LoggingConfiguration;
 import org.jboss.resteasy.reactive.server.ServerRequestFilter;
 import org.jboss.resteasy.reactive.server.ServerResponseFilter;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-public class RequestIdFilter {
+public class CorrelationIdFilter {
 
-  public static final String REQUEST_ID_KEY = "requestId";
+  public static final String CORRELATION_ID_KEY = "requestId";
 
-  private static final Logger LOGGER = LoggerFactory.getLogger(RequestIdFilter.class);
+  private static final Logger LOGGER = LoggerFactory.getLogger(CorrelationIdFilter.class);
 
-  @Inject LoggingConfiguration loggingConfiguration;
-  @Inject RequestIdGenerator requestIdGenerator;
+  @Inject CorrelationIdConfiguration correlationIdConfiguration;
+  @Inject CorrelationIdGenerator correlationIdGenerator;
 
-  @ServerRequestFilter(preMatching = true, priority = FilterPriorities.REQUEST_ID_FILTER)
+  @ServerRequestFilter(preMatching = true, priority = FilterPriorities.CORRELATION_ID_FILTER)
   public Uni<Response> assignRequestId(ContainerRequestContext rc) {
-    var requestId = rc.getHeaderString(loggingConfiguration.requestIdHeaderName());
-    return (requestId != null
-            ? Uni.createFrom().item(requestId)
-            : requestIdGenerator.generateRequestId(rc))
+    var correlationId = rc.getHeaderString(correlationIdConfiguration.headerName());
+    return (correlationId != null
+            ? Uni.createFrom().item(correlationId)
+            : correlationIdGenerator.generateCorrelationId(rc))
         .onItem()
-        .invoke(id -> rc.setProperty(REQUEST_ID_KEY, id))
+        .invoke(id -> rc.setProperty(CORRELATION_ID_KEY, id))
         .onItemOrFailure()
         .transform((id, error) -> error == null ? null : errorResponse(error));
   }
 
   @ServerResponseFilter
   public void addResponseHeader(
       ContainerRequestContext request, ContainerResponseContext response) {
-    String requestId = (String) request.getProperty(REQUEST_ID_KEY);
-    if (requestId != null) { // can be null if request ID generation fails
-      response.getHeaders().add(loggingConfiguration.requestIdHeaderName(), requestId);
+    String correlationId = (String) request.getProperty(CORRELATION_ID_KEY);
+    if (correlationId != null) { // can be null if request ID generation fails
+      response.getHeaders().add(correlationIdConfiguration.headerName(), correlationId);
     }
   }