From 8149cc94ff1803cd7afe86f38680893ad727e5c5 Mon Sep 17 00:00:00 2001
From: jack-berg <34418638+jack-berg@users.noreply.github.com>
Date: Tue, 19 Nov 2024 02:47:58 -0600
Subject: [PATCH] Java documentation for cardinality limits (#5610)

Co-authored-by: Patrice Chalin <pchalin@gmail.com>
---
 .gitmodules                                 |  2 +-
 content-modules/opentelemetry-java-examples |  2 +-
 content/en/docs/languages/java/sdk.md       | 24 ++++++++++++++++++++-
 static/refcache.json                        |  4 ++++
 tools/pubspec.yaml                          |  2 +-
 5 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/.gitmodules b/.gitmodules
index a78309399754..81e7ea448e3c 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -31,4 +31,4 @@
 [submodule "content-modules/opentelemetry-java-examples"]
 	path = content-modules/opentelemetry-java-examples
 	url = https://github.com/open-telemetry/opentelemetry-java-examples.git
-	javaexamples-pin = 0f736ec
+	javaexamples-pin = f9553ef
diff --git a/content-modules/opentelemetry-java-examples b/content-modules/opentelemetry-java-examples
index 0f736eca6a4b..f9553eff58aa 160000
--- a/content-modules/opentelemetry-java-examples
+++ b/content-modules/opentelemetry-java-examples
@@ -1 +1 @@
-Subproject commit 0f736eca6a4b6865fb62b00033a53369e69440f7
+Subproject commit f9553eff58aabb28dabee8c14274d9860b4c52bd
diff --git a/content/en/docs/languages/java/sdk.md b/content/en/docs/languages/java/sdk.md
index 6d88d1eea512..ef4b13c07a8c 100644
--- a/content/en/docs/languages/java/sdk.md
+++ b/content/en/docs/languages/java/sdk.md
@@ -565,6 +565,14 @@ responsible for handling metric telemetry produced by the API.
 
 - [Resource](#resource): The resource metrics are associated with.
 - [MetricReader](#metricreader): Reads the aggregated state of metrics.
+  - Optionally, with
+    [CardinalityLimitSelector](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-metrics/latest/io/opentelemetry/sdk/metrics/export/CardinalityLimitSelector.html)
+    for overriding cardinality limit by instrument kind. If unset, each
+    instrument is limited to 2000 unique combinations of attributes per
+    collection cycle. Cardinality limits are also configurable for individual
+    instruments via [views](#views). See
+    [cardinality limits](/docs/specs/otel/metrics/sdk/#cardinality-limits) for
+    more details.
 - [MetricExporter](#metricexporter): Exports metrics out of process (in
   conjunction with associated `MetricReader`).
 - [Views](#views): Configures metric streams, including dropping unused metrics.
@@ -592,11 +600,18 @@ public class SdkMeterProviderConfig {
                 MetricReaderConfig.periodicMetricReader(
                     MetricExporterConfig.otlpHttpMetricExporter(
                         "http://localhost:4318/v1/metrics")));
+    // Uncomment to optionally register metric reader with cardinality limits
+    // builder.registerMetricReader(
+    //     MetricReaderConfig.periodicMetricReader(
+    //         MetricExporterConfig.otlpHttpMetricExporter("http://localhost:4318/v1/metrics")),
+    //     instrumentType -> 100);
+
     ViewConfig.dropMetricView(builder, "some.custom.metric");
     ViewConfig.histogramBucketBoundariesView(
         builder, "http.server.request.duration", List.of(1.0, 5.0, 10.0));
     ViewConfig.attributeFilterView(
         builder, "http.client.request.duration", Set.of("http.request.method"));
+    ViewConfig.cardinalityLimitsView(builder, "http.server.active_requests", 100);
     return builder.build();
   }
 }
@@ -872,7 +887,7 @@ public class CustomMetricExporter implements MetricExporter {
 [Views](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-metrics/latest/io/opentelemetry/sdk/metrics/View.html)
 allow metric streams to be customized, including changing metric names, metric
 descriptions, metric aggregations (i.e. histogram bucket boundaries), the set of
-attribute keys to retain, etc.
+attribute keys to retain, cardinality limit, etc.
 
 {{% alert %}} Views have somewhat unintuitive behavior when multiple match a
 particular instrument. If one matching view changes the metric name and another
@@ -920,6 +935,13 @@ public class ViewConfig {
         InstrumentSelector.builder().setName(metricName).build(),
         View.builder().setAttributeFilter(keysToRetain).build());
   }
+
+  public static SdkMeterProviderBuilder cardinalityLimitsView(
+      SdkMeterProviderBuilder builder, String metricName, int cardinalityLimit) {
+    return builder.registerView(
+        InstrumentSelector.builder().setName(metricName).build(),
+        View.builder().setCardinalityLimit(cardinalityLimit).build());
+  }
 }
 ```
 <!-- prettier-ignore-end -->
diff --git a/static/refcache.json b/static/refcache.json
index 6474e0faf555..084a93c50e2e 100644
--- a/static/refcache.json
+++ b/static/refcache.json
@@ -13767,6 +13767,10 @@
     "StatusCode": 200,
     "LastSeen": "2024-08-05T15:20:09.004763-05:00"
   },
+  "https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-metrics/latest/io/opentelemetry/sdk/metrics/export/CardinalityLimitSelector.html": {
+    "StatusCode": 200,
+    "LastSeen": "2024-11-14T12:48:43.848396-06:00"
+  },
   "https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-metrics/latest/io/opentelemetry/sdk/metrics/export/MetricExporter.html": {
     "StatusCode": 200,
     "LastSeen": "2024-08-05T15:20:07.498447-05:00"
diff --git a/tools/pubspec.yaml b/tools/pubspec.yaml
index f6fcf96b2545..3a5410ae2f0e 100644
--- a/tools/pubspec.yaml
+++ b/tools/pubspec.yaml
@@ -2,7 +2,7 @@ name: otel_io_excerpts
 publish_to: none
 
 environment:
-  sdk: ^3.2.0
+  sdk: ^3.5.4
 
 dev_dependencies:
   build_runner: ^2.4.6