Lettuce metadata

docs/instrumentation-list.yaml

@@ -7801,20 +7801,193 @@ libraries:
           type: STRING
   lettuce:
   - name: lettuce-4.0
+    description: |
+      This instrumentation enables database client spans and database client metrics for the Lettuce Redis client.
+    semantic_conventions:
+    - DATABASE_CLIENT_SPANS
+    - DATABASE_CLIENT_METRICS
+    library_link: https://github.com/redis/lettuce
     source_path: instrumentation/lettuce/lettuce-4.0
     scope:
       name: io.opentelemetry.lettuce-4.0
     target_versions:
       javaagent:
       - biz.paluch.redis:lettuce:[4.0.Final,)
+    configurations:
+    - name: otel.instrumentation.lettuce.connection-telemetry.enabled
+      description: Enables connection telemetry spans for Redis connections.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.lettuce.experimental-span-attributes
+      description: Enables experimental span attribute `lettuce.command.cancelled`.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.common.peer-service-mapping
+      description: Used to specify a mapping from host names or IP addresses to peer
+        services.
+      type: map
+      default: ''
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: db.operation
+          type: STRING
+        - name: db.system
+          type: STRING
+        - name: peer.service
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+    - when: otel.instrumentation.lettuce.experimental-span-attributes=true
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: db.operation
+          type: STRING
+        - name: db.system
+          type: STRING
+        - name: lettuce.command.cancelled
+          type: BOOLEAN
+        - name: peer.service
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+    - when: otel.semconv-stability.opt-in=database
+      metrics:
+      - name: db.client.operation.duration
+        description: Duration of database client operations.
+        type: HISTOGRAM
+        unit: s
+        attributes:
+        - name: db.operation.name
+          type: STRING
+        - name: db.system.name
+          type: STRING
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: db.operation.name
+          type: STRING
+        - name: db.system.name
+          type: STRING
+        - name: error.type
+          type: STRING
+        - name: peer.service
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
   - name: lettuce-5.0
+    description: |
+      This instrumentation enables database client spans and database client metrics for the Lettuce Redis client.
+    semantic_conventions:
+    - DATABASE_CLIENT_SPANS
+    - DATABASE_CLIENT_METRICS
+    library_link: https://github.com/redis/lettuce
     source_path: instrumentation/lettuce/lettuce-5.0
     scope:
       name: io.opentelemetry.lettuce-5.0
     target_versions:
       javaagent:
       - io.lettuce:lettuce-core:[5.0.0.RELEASE,5.1.0.RELEASE)
+    configurations:
+    - name: otel.instrumentation.lettuce.connection-telemetry.enabled
+      description: Enables connection telemetry spans for Redis connections.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.lettuce.experimental-span-attributes
+      description: |
+        Enables experimental span attributes `lettuce.command.cancelled` and `lettuce.command.results.count`.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.common.db-statement-sanitizer.enabled
+      description: Enables statement sanitization for database queries.
+      type: boolean
+      default: true
+    - name: otel.instrumentation.common.peer-service-mapping
+      description: Used to specify a mapping from host names or IP addresses to peer
+        services.
+      type: map
+      default: ''
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: db.operation
+          type: STRING
+        - name: db.statement
+          type: STRING
+        - name: db.system
+          type: STRING
+        - name: peer.service
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+    - when: otel.instrumentation.lettuce.experimental-span-attributes=true
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: db.operation
+          type: STRING
+        - name: db.statement
+          type: STRING
+        - name: db.system
+          type: STRING
+        - name: lettuce.command.cancelled
+          type: BOOLEAN
+        - name: lettuce.command.results.count
+          type: LONG
+        - name: peer.service
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+    - when: otel.semconv-stability.opt-in=database
+      metrics:
+      - name: db.client.operation.duration
+        description: Duration of database client operations.
+        type: HISTOGRAM
+        unit: s
+        attributes:
+        - name: db.operation.name
+          type: STRING
+        - name: db.system.name
+          type: STRING
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: db.operation.name
+          type: STRING
+        - name: db.query.text
+          type: STRING
+        - name: db.system.name
+          type: STRING
+        - name: error.type
+          type: STRING
+        - name: peer.service
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
   - name: lettuce-5.1
+    description: |
+      This instrumentation enables database client spans and database client metrics for the Lettuce Redis client.
+    semantic_conventions:
+    - DATABASE_CLIENT_SPANS
+    - DATABASE_CLIENT_METRICS
+    library_link: https://github.com/redis/lettuce
     source_path: instrumentation/lettuce/lettuce-5.1
     scope:
       name: io.opentelemetry.lettuce-5.1
@@ -7823,6 +7996,73 @@ libraries:
       - io.lettuce:lettuce-core:[5.1.0.RELEASE,)
       library:
       - io.lettuce:lettuce-core:5.1.0.RELEASE
+    configurations:
+    - name: otel.instrumentation.lettuce.experimental.command-encoding-events.enabled
+      description: Enables capturing `redis.encode.start` and `redis.encode.end` span
+        events.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.common.db-statement-sanitizer.enabled
+      description: Enables statement sanitization for database queries.
+      type: boolean
+      default: true
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: db.statement
+          type: STRING
+        - name: db.system
+          type: STRING
+        - name: error
+          type: STRING
+        - name: network.peer.address
+          type: STRING
+        - name: network.peer.port
+          type: LONG
+        - name: network.type
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+    - when: otel.semconv-stability.opt-in=database
+      metrics:
+      - name: db.client.operation.duration
+        description: Duration of database client operations.
+        type: HISTOGRAM
+        unit: s
+        attributes:
+        - name: db.system.name
+          type: STRING
+        - name: network.peer.address
+          type: STRING
+        - name: network.peer.port
+          type: LONG
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: db.query.text
+          type: STRING
+        - name: db.system.name
+          type: STRING
+        - name: error
+          type: STRING
+        - name: network.peer.address
+          type: STRING
+        - name: network.peer.port
+          type: LONG
+        - name: network.type
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
   liberty:
   - name: liberty-20.0
     source_path: instrumentation/liberty/liberty-20.0

instrumentation-docs/instrumentations.sh

@@ -158,6 +158,14 @@ readonly INSTRUMENTATIONS=(
   "ktor:ktor-3.0:library:test"
   "kubernetes-client-7.0:javaagent:test"
   "kubernetes-client-7.0:javaagent:testExperimental"
+  "lettuce:lettuce-4.0:javaagent:test"
+  "lettuce:lettuce-4.0:javaagent:testExperimental"
+  "lettuce:lettuce-4.0:javaagent:testStableSemconv"
+  "lettuce:lettuce-5.0:javaagent:test"
+  "lettuce:lettuce-5.0:javaagent:testExperimental"
+  "lettuce:lettuce-5.0:javaagent:testStableSemconv"
+  "lettuce:lettuce-5.1:javaagent:test"
+  "lettuce:lettuce-5.1:javaagent:testStableSemconv"
   "nats:nats-2.17:javaagent:test"
   "nats:nats-2.17:javaagent:testExperimental"
   "netty:netty-3.8:javaagent:test"

instrumentation/lettuce/lettuce-4.0/javaagent/build.gradle.kts

@@ -22,20 +22,27 @@ dependencies {
 
 tasks {
   withType<Test>().configureEach {
-    // TODO run tests both with and without experimental span attributes and span events
-    jvmArgs("-Dotel.instrumentation.lettuce.experimental-span-attributes=true")
     jvmArgs("-Dotel.instrumentation.lettuce.connection-telemetry.enabled=true")
-    jvmArgs("-Dotel.instrumentation.lettuce.experimental.command-encoding-events.enabled=true")
     usesService(gradle.sharedServices.registrations["testcontainersBuildService"].service)
+    systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
+  }
+
+  val testExperimental by registering(Test::class) {
+    testClassesDirs = sourceSets.test.get().output.classesDirs
+    classpath = sourceSets.test.get().runtimeClasspath
+
+    jvmArgs("-Dotel.instrumentation.lettuce.experimental-span-attributes=true")
+    systemProperty("metadataConfig", "otel.instrumentation.lettuce.experimental-span-attributes=true")
   }
 
   val testStableSemconv by registering(Test::class) {
     testClassesDirs = sourceSets.test.get().output.classesDirs
     classpath = sourceSets.test.get().runtimeClasspath
     jvmArgs("-Dotel.semconv-stability.opt-in=database")
+    systemProperty("metadataConfig", "otel.semconv-stability.opt-in=database")
   }
 
   check {
-    dependsOn(testStableSemconv)
+    dependsOn(testStableSemconv, testExperimental)
   }
 }

instrumentation/lettuce/lettuce-4.0/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/lettuce/v4_0/ExperimentalHelper.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.javaagent.instrumentation.lettuce.v4_0;
+
+import javax.annotation.Nullable;
+
+class ExperimentalHelper {
+
+  private static final boolean EXPERIMENTAL_ATTRIBUTES_ENABLED =
+      Boolean.getBoolean("otel.instrumentation.lettuce.experimental-span-attributes");
+
+  @Nullable
+  static <T> T experimental(T value) {
+    return EXPERIMENTAL_ATTRIBUTES_ENABLED ? value : null;
+  }
+
+  private ExperimentalHelper() {}
+}

instrumentation/lettuce/lettuce-4.0/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/lettuce/v4_0/LettuceAsyncClientTest.java

@@ -7,6 +7,7 @@
 
 import static io.opentelemetry.api.common.AttributeKey.booleanKey;
 import static io.opentelemetry.instrumentation.testing.junit.db.SemconvStabilityUtil.maybeStable;
+import static io.opentelemetry.javaagent.instrumentation.lettuce.v4_0.ExperimentalHelper.experimental;
 import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.equalTo;
 import static io.opentelemetry.semconv.ErrorAttributes.ERROR_TYPE;
 import static io.opentelemetry.semconv.ServerAttributes.SERVER_ADDRESS;
@@ -476,7 +477,7 @@ void testCommandBeforeItFinished() {
                         .hasAttributesSatisfyingExactly(
                             equalTo(maybeStable(DB_SYSTEM), "redis"),
                             equalTo(maybeStable(DB_OPERATION), "SADD"),
-                            equalTo(booleanKey("lettuce.command.cancelled"), true)),
+                            equalTo(booleanKey("lettuce.command.cancelled"), experimental(true))),
                 span ->
                     span.hasName("callback")
                         .hasKind(SpanKind.INTERNAL)

instrumentation/lettuce/lettuce-4.0/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/lettuce/v4_0/LettuceSyncClientTest.java

@@ -5,8 +5,11 @@
 
 package io.opentelemetry.javaagent.instrumentation.lettuce.v4_0;
 
+import static io.opentelemetry.instrumentation.testing.junit.db.DbClientMetricsTestUtil.assertDurationMetric;
 import static io.opentelemetry.instrumentation.testing.junit.db.SemconvStabilityUtil.maybeStable;
 import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.equalTo;
+import static io.opentelemetry.semconv.DbAttributes.DB_OPERATION_NAME;
+import static io.opentelemetry.semconv.DbAttributes.DB_SYSTEM_NAME;
 import static io.opentelemetry.semconv.ServerAttributes.SERVER_ADDRESS;
 import static io.opentelemetry.semconv.ServerAttributes.SERVER_PORT;
 import static io.opentelemetry.semconv.incubating.DbIncubatingAttributes.DB_OPERATION;
@@ -43,7 +46,7 @@ class LettuceSyncClientTest {
   private static final Logger logger = LoggerFactory.getLogger(LettuceSyncClientTest.class);
 
   @RegisterExtension
-  protected static final InstrumentationExtension testing = AgentInstrumentationExtension.create();
+  static final InstrumentationExtension testing = AgentInstrumentationExtension.create();
 
   @RegisterExtension static final AutoCleanupExtension cleanup = AutoCleanupExtension.create();
 
@@ -169,6 +172,9 @@ void testSetCommand() {
                         .hasAttributesSatisfyingExactly(
                             equalTo(maybeStable(DB_SYSTEM), "redis"),
                             equalTo(maybeStable(DB_OPERATION), "SET"))));
+
+    assertDurationMetric(
+        testing, "io.opentelemetry.lettuce-4.0", DB_SYSTEM_NAME, DB_OPERATION_NAME);
   }
 
   @Test