initial TelemetryPolicy (#2592)

Author: jackshirazi

dynamic-control/build.gradle.kts

@@ -16,6 +16,8 @@ dependencies {
   annotationProcessor("com.google.auto.service:auto-service")
   compileOnly("com.google.auto.service:auto-service-annotations")
 
+  implementation("com.fasterxml.jackson.core:jackson-databind")
+
   compileOnly("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
   compileOnly("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi")
 

dynamic-control/src/main/java/io/opentelemetry/contrib/dynamic/policy/TelemetryPolicy.java

@@ -0,0 +1,88 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.contrib.dynamic.policy;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import java.util.Objects;
+import javax.annotation.Nullable;
+
+/**
+ * Represents a single Telemetry Policy, comprising a type and a specification.
+ *
+ * <p>A {@code TelemetryPolicy} instance encapsulates a specific rule or configuration intent
+ * identified by its {@link #getType() type}. The behavior of the policy is defined by its {@link
+ * #getSpec() specification}, which is a JSON object.
+ *
+ * <p>Policies are typically immutable data carriers. The {@code spec} can be {@code null}, which
+ * conventionally signifies the removal or absence of a policy for the given type in certain
+ * contexts (e.g., when calculating diffs or updates).
+ *
+ * <p>As an example take the JSON structure `{"trace-sampling": {"probability" : 0.5}}` This is of
+ * type "trace-sampling", with spec `{"probability" : 0.5}`, indicating the intent that the trace
+ * sampling-probability be set to 50%
+ *
+ * @see io.opentelemetry.contrib.dynamic.policy
+ */
+public class TelemetryPolicy {
+  private final String type; // e.g. "trace-sampling"
+  // JSON content after schema validation
+  // null means removed, which is relevant for merging policies
+  @Nullable private final JsonNode spec;
+
+  /**
+   * Constructs a new TelemetryPolicy.
+   *
+   * @param type the type of the policy (e.g., "trace-sampling"), must not be null.
+   * @param spec the JSON specification of the policy, or {@code null} to indicate removal.
+   */
+  public TelemetryPolicy(String type, @Nullable JsonNode spec) {
+    Objects.requireNonNull(type, "type cannot be null");
+    this.type = type;
+    this.spec = spec;
+  }
+
+  /**
+   * Returns the type of this policy.
+   *
+   * <p>The type identifies the domain and expected behavior of the policy (e.g., "trace-sampling",
+   * "metric-rate").
+   *
+   * @return the policy type.
+   */
+  public String getType() {
+    return type;
+  }
+
+  /**
+   * Returns the specification of this policy.
+   *
+   * <p>The specification is a JSON structure defining the parameters of the policy. If {@code
+   * null}, it may indicate that the policy is being removed or is empty.
+   *
+   * @return the policy specification, or {@code null}.
+   */
+  @Nullable
+  public JsonNode getSpec() {
+    return spec;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) {
+      return true;
+    }
+    if (!(o instanceof TelemetryPolicy)) {
+      return false;
+    }
+    TelemetryPolicy that = (TelemetryPolicy) o;
+    return Objects.equals(type, that.type) && Objects.equals(spec, that.spec);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(type, spec);
+  }
+}

dynamic-control/src/main/java/io/opentelemetry/contrib/dynamic/policy/package-info.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Defines the Telemetry Policy API, a mechanism for intent-based specification of telemetry
+ * behavior.
+ *
+ * <p>A Telemetry Policy is a distinct rule that governs how telemetry data is collected, processed,
+ * or exported. Unlike traditional configuration, which often describes a pipeline of specific
+ * components, a policy describes the <em>desired outcome</em> (the intent) and is
+ * implementation-agnostic.
+ *
+ * <h2>Key Characteristics</h2>
+ *
+ * <ul>
+ *   <li><strong>Typed:</strong> Each policy has a type (e.g., {@code trace-sampling}, {@code
+ *       log-filter}) that defines its domain and behavior.
+ *   <li><strong>Implementation Agnostic:</strong> The same policy definition can be enforced by an
+ *       SDK, a Collector, or any other component that understands the policy type.
+ *   <li><strong>Standalone:</strong> Policies are atomic and self-contained. They do not depend on
+ *       pipeline configuration or other policies.
+ *   <li><strong>Dynamic:</strong> Policies are designed to be updated at runtime, allowing behavior
+ *       to change without restarting the application.
+ *   <li><strong>Idempotent:</strong> Policies can be applied multiple times safely. The system
+ *       converges to the desired state.
+ * </ul>
+ *
+ * <h2>Architecture</h2>
+ *
+ * <p>The telemetry policy ecosystem typically consists of:
+ *
+ * <ul>
+ *   <li><strong>Policy Providers:</strong> Sources of policies (e.g., a file, an HTTP endpoint, an
+ *       OpAMP server).
+ *   <li><strong>Policy Aggregator:</strong> Merges policies from multiple providers. Policies of
+ *       the same type are merged (e.g., using JSON Merge Patch), while policies of different types
+ *       coexist.
+ *   <li><strong>Policy Implementations:</strong> Components that react to policy updates and
+ *       enforce the specified behavior (e.g., updating a trace sampler).
+ * </ul>
+ *
+ * @see io.opentelemetry.contrib.dynamic.policy.TelemetryPolicy
+ */
+@ParametersAreNonnullByDefault
+package io.opentelemetry.contrib.dynamic.policy;
+
+import javax.annotation.ParametersAreNonnullByDefault;