Add initial audit logging pipeline (API, SDK, OTLP exporter, and autoconfigure)

api/all/src/main/java/io/opentelemetry/api/audit/ActorType.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.audit;
+
+/**
+ * Classifies the kind of entity that performed an auditable action.
+ *
+ * @see AuditRecordBuilder#setActorType(ActorType)
+ */
+public enum ActorType {
+
+  /** A human user, identified by a user account. */
+  USER,
+
+  /** An automated service, daemon, or service account. */
+  SERVICE,
+
+  /** The operating system or a privileged system component. */
+  SYSTEM
+}

api/all/src/main/java/io/opentelemetry/api/audit/AuditDeliveryException.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.audit;
+
+/**
+ * Hard-error thrown by {@link AuditRecordBuilder#emit()} when the audit sink cannot be reached and
+ * all retries are exhausted. This is an unchecked exception so that audit-logging call sites remain
+ * clean, but callers SHOULD catch it and escalate the failure through their incident-management
+ * process.
+ */
+public final class AuditDeliveryException extends RuntimeException {
+
+  private static final long serialVersionUID = 1L;
+
+  public AuditDeliveryException(String message) {
+    super(message);
+  }
+
+  public AuditDeliveryException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

api/all/src/main/java/io/opentelemetry/api/audit/AuditLogger.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.audit;
+
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * The entry point for emitting audit records.
+ *
+ * <p>Obtain an {@link AuditRecordBuilder} via {@link #auditRecordBuilder()}, populate all required
+ * fields, and call {@link AuditRecordBuilder#emit()} to deliver the record to the audit sink.
+ *
+ * <p>Unlike {@link io.opentelemetry.api.logs.Logger}, this interface does <em>not</em> expose an
+ * {@code isEnabled} check: audit records are ALWAYS emitted. Dropping audit records is prohibited
+ * by the audit logging specification.
+ */
+@ThreadSafe
+public interface AuditLogger {
+
+  /** Returns an {@link AuditRecordBuilder} for constructing and emitting an audit record. */
+  AuditRecordBuilder auditRecordBuilder();
+}

api/all/src/main/java/io/opentelemetry/api/audit/AuditLoggerBuilder.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.audit;
+
+/**
+ * Builder for creating named {@link AuditLogger} instances.
+ *
+ * <p>The {@code name} (set on the owning {@link AuditProvider}) is stored as a diagnostic label on
+ * the logger. Unlike {@link io.opentelemetry.api.logs.LoggerBuilder}, the name is NOT mapped to an
+ * OTLP {@code InstrumentationScope}.
+ */
+public interface AuditLoggerBuilder {
+
+  /**
+   * Sets the schema URL to be recorded on emitted {@link AuditRecordBuilder}s for semantic
+   * convention versioning.
+   */
+  AuditLoggerBuilder setSchemaUrl(String schemaUrl);
+
+  /** Sets the version of the component or library that is emitting audit records. */
+  AuditLoggerBuilder setInstrumentationVersion(String instrumentationVersion);
+
+  /** Returns the configured {@link AuditLogger}. */
+  AuditLogger build();
+}

api/all/src/main/java/io/opentelemetry/api/audit/AuditProvider.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.audit;
+
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * The entry point of the Audit Logging API. Provides named {@link AuditLogger} instances.
+ *
+ * <p>The provider is expected to be accessed from a central place. Use {@link
+ * GlobalAuditProvider#get()} to obtain the globally registered instance, or create an {@link
+ * AuditProvider} directly via the SDK.
+ *
+ * <p>When no SDK is installed, {@link #noop()} returns an {@link AuditProvider} whose loggers emit
+ * no-op receipts without error.
+ */
+@ThreadSafe
+public interface AuditProvider {
+
+  /**
+   * Gets or creates a named {@link AuditLogger} instance.
+   *
+   * @param name A string identifying the component or subsystem emitting audit records (for example
+   *     {@code "com.example.auth"}). MUST NOT be empty.
+   */
+  default AuditLogger get(String name) {
+    return auditLoggerBuilder(name).build();
+  }
+
+  /**
+   * Creates an {@link AuditLoggerBuilder} for a named {@link AuditLogger}.
+   *
+   * @param name A string identifying the component or subsystem emitting audit records. MUST NOT be
+   *     empty.
+   */
+  AuditLoggerBuilder auditLoggerBuilder(String name);
+
+  /**
+   * Returns a no-op {@link AuditProvider} whose loggers return no-op {@link AuditReceipt}s
+   * immediately without error.
+   */
+  static AuditProvider noop() {
+    return DefaultAuditProvider.getInstance();
+  }
+}

api/all/src/main/java/io/opentelemetry/api/audit/AuditReceipt.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.audit;
+
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * Proof-of-delivery returned by {@link AuditLogger} once the audit sink has persisted the record.
+ *
+ * <p>The {@code recordId} echoes the caller's {@link AuditRecordBuilder#setRecordId(String)}.
+ * {@code integrityHash} is the SHA-256 of the record as written by the sink. {@code
+ * sinkTimestampEpochNanos} is the nanosecond UNIX epoch at which the sink persisted the record.
+ */
+@Immutable
+public final class AuditReceipt {
+
+  private final String recordId;
+  private final String integrityHash;
+  private final long sinkTimestampEpochNanos;
+
+  private AuditReceipt(String recordId, String integrityHash, long sinkTimestampEpochNanos) {
+    this.recordId = recordId;
+    this.integrityHash = integrityHash;
+    this.sinkTimestampEpochNanos = sinkTimestampEpochNanos;
+  }
+
+  /** Creates an {@link AuditReceipt} with the given fields. */
+  public static AuditReceipt create(
+      String recordId, String integrityHash, long sinkTimestampEpochNanos) {
+    return new AuditReceipt(recordId, integrityHash, sinkTimestampEpochNanos);
+  }
+
+  /** Returns the {@code RecordId} echoed from the corresponding {@link AuditRecordBuilder}. */
+  public String recordId() {
+    return recordId;
+  }
+
+  /**
+   * Returns the SHA-256 hex digest of the canonical serialization of the {@code AuditRecord} as
+   * persisted by the audit sink.
+   */
+  public String integrityHash() {
+    return integrityHash;
+  }
+
+  /** Returns the nanosecond UNIX epoch at which the audit sink persisted the record. */
+  public long sinkTimestampEpochNanos() {
+    return sinkTimestampEpochNanos;
+  }
+
+  @Override
+  public boolean equals(Object obj) {
+    if (this == obj) {
+      return true;
+    }
+    if (!(obj instanceof AuditReceipt)) {
+      return false;
+    }
+    AuditReceipt other = (AuditReceipt) obj;
+    return recordId.equals(other.recordId)
+        && integrityHash.equals(other.integrityHash)
+        && sinkTimestampEpochNanos == other.sinkTimestampEpochNanos;
+  }
+
+  @Override
+  public int hashCode() {
+    int result = recordId.hashCode();
+    result = 31 * result + integrityHash.hashCode();
+    result = 31 * result + Long.hashCode(sinkTimestampEpochNanos);
+    return result;
+  }
+
+  @Override
+  public String toString() {
+    return "AuditReceipt{"
+        + "recordId="
+        + recordId
+        + ", integrityHash="
+        + integrityHash
+        + ", sinkTimestampEpochNanos="
+        + sinkTimestampEpochNanos
+        + "}";
+  }
+}