From 3ff825807f53a7074501ee176dfaa5eaa1faed5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Barto=C5=A1?= Date: Tue, 13 Aug 2024 13:20:37 +0200 Subject: [PATCH] Tracing - Configurable service name and resource attributes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #32056 Signed-off-by: Martin Bartoš --- docs/guides/server/tracing.adoc | 5 ++ .../org/keycloak/config/TracingOptions.java | 11 ++++ .../mappers/TracingPropertyMappers.java | 12 +++++ .../test/TracingConfigurationTest.java | 51 ++++++++++++++++++- .../keycloak/it/cli/dist/TracingDistTest.java | 40 +++++++++++++-- ...andDistTest.testExportHelpAll.approved.txt | 9 ++++ ...andDistTest.testImportHelpAll.approved.txt | 9 ++++ ...dDistTest.testStartDevHelpAll.approved.txt | 9 ++++ ...mandDistTest.testStartHelpAll.approved.txt | 9 ++++ ...est.testStartOptimizedHelpAll.approved.txt | 9 ++++ 10 files changed, 160 insertions(+), 4 deletions(-) diff --git a/docs/guides/server/tracing.adoc b/docs/guides/server/tracing.adoc index 7cc579e5d1..ef181da7c8 100644 --- a/docs/guides/server/tracing.adoc +++ b/docs/guides/server/tracing.adoc @@ -22,6 +22,11 @@ It is possible to enable exposing traces using the build time option `tracing-en <@kc.start parameters="--tracing-enabled=true"/> By default, the trace exporters send out data in batches, using the `gRPC` protocol and endpoint `+http://localhost:4317+`. + +The default service name is `keycloak`, specified via the `tracing-service-name` property, which takes precedence over `service.name` defined in the `tracing-resource-attributes` property. + +For more information about resource attributes that can be provided via the `tracing-resource-attributes` property, see the https://quarkus.io/guides/opentelemetry#resource[Quarkus OpenTelemetry Resource] guide. + For more tracing settings, see all possible configurations below. == Development setup diff --git a/quarkus/config-api/src/main/java/org/keycloak/config/TracingOptions.java b/quarkus/config-api/src/main/java/org/keycloak/config/TracingOptions.java index 9bdce6b174..aa14757570 100644 --- a/quarkus/config-api/src/main/java/org/keycloak/config/TracingOptions.java +++ b/quarkus/config-api/src/main/java/org/keycloak/config/TracingOptions.java @@ -20,6 +20,7 @@ package org.keycloak.config; import io.quarkus.opentelemetry.runtime.config.build.SamplerType; import java.util.Arrays; +import java.util.List; public class TracingOptions { @@ -43,6 +44,16 @@ public class TracingOptions { .buildTime(true) .build(); + public static final Option TRACING_SERVICE_NAME = new OptionBuilder<>("tracing-service-name", String.class) + .category(OptionCategory.TRACING) + .description("OpenTelemetry service name. Takes precedence over 'service.name' defined in the 'tracing-resource-attributes' property.") + .defaultValue("keycloak") + .build(); + + public static final Option> TRACING_RESOURCE_ATTRIBUTES = OptionBuilder.listOptionBuilder("tracing-resource-attributes", String.class) + .category(OptionCategory.TRACING) + .description("OpenTelemetry resource attributes present in the exported trace to characterize the telemetry producer. Values in format 'key1=val1,key2=val2'. For more information, check the Tracing guide.") + .build(); public static final Option TRACING_PROTOCOL = new OptionBuilder<>("tracing-protocol", String.class) .category(OptionCategory.TRACING) .description("OpenTelemetry protocol used for the telemetry data.") diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/TracingPropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/TracingPropertyMappers.java index c70e504417..f50b59a95d 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/TracingPropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/TracingPropertyMappers.java @@ -31,8 +31,10 @@ import static org.keycloak.config.TracingOptions.TRACING_ENABLED; import static org.keycloak.config.TracingOptions.TRACING_ENDPOINT; import static org.keycloak.config.TracingOptions.TRACING_JDBC_ENABLED; import static org.keycloak.config.TracingOptions.TRACING_PROTOCOL; +import static org.keycloak.config.TracingOptions.TRACING_RESOURCE_ATTRIBUTES; import static org.keycloak.config.TracingOptions.TRACING_SAMPLER_RATIO; import static org.keycloak.config.TracingOptions.TRACING_SAMPLER_TYPE; +import static org.keycloak.config.TracingOptions.TRACING_SERVICE_NAME; import static org.keycloak.quarkus.runtime.configuration.mappers.PropertyMapper.fromOption; public class TracingPropertyMappers { @@ -52,6 +54,16 @@ public class TracingPropertyMappers { .paramLabel("url") .validator(TracingPropertyMappers::validateEndpoint) .build(), + fromOption(TRACING_SERVICE_NAME) + .isEnabled(TracingPropertyMappers::isTracingEnabled, TRACING_ENABLED_MSG) + .to("quarkus.otel.service.name") + .paramLabel("name") + .build(), + fromOption(TRACING_RESOURCE_ATTRIBUTES) + .isEnabled(TracingPropertyMappers::isTracingEnabled, TRACING_ENABLED_MSG) + .to("quarkus.otel.resource.attributes") + .paramLabel("attributes") + .build(), fromOption(TRACING_PROTOCOL) .isEnabled(TracingPropertyMappers::isTracingEnabled, TRACING_ENABLED_MSG) .to("quarkus.otel.exporter.otlp.traces.protocol") diff --git a/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/configuration/test/TracingConfigurationTest.java b/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/configuration/test/TracingConfigurationTest.java index d968a603ed..9219e06225 100644 --- a/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/configuration/test/TracingConfigurationTest.java +++ b/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/configuration/test/TracingConfigurationTest.java @@ -43,9 +43,11 @@ public class TracingConfigurationTest extends AbstractConfigurationTest { "log-file-include-trace", "true", "log-syslog-include-trace", "true" )); + assertConfig("tracing-service-name", "keycloak"); assertExternalConfig(Map.of( "quarkus.otel.traces.enabled", "false", + "quarkus.otel.service.name", "keycloak", "quarkus.otel.exporter.otlp.traces.endpoint", "http://localhost:4317", "quarkus.otel.exporter.otlp.traces.protocol", "grpc", "quarkus.datasource.jdbc.telemetry", "false", @@ -69,6 +71,10 @@ public class TracingConfigurationTest extends AbstractConfigurationTest { "KC_LOG_FILE_INCLUDE_TRACE", "false", "KC_LOG_SYSLOG_INCLUDE_TRACE", "false" )); + putEnvVars(Map.of( + "KC_TRACING_SERVICE_NAME", "keycloak-42", + "KC_TRACING_RESOURCE_ATTRIBUTES", "host.name=unknown,service.version=30" + )); initConfig(); @@ -80,6 +86,10 @@ public class TracingConfigurationTest extends AbstractConfigurationTest { "tracing-sampler-type", SamplerType.PARENT_BASED_ALWAYS_ON.getValue(), "tracing-sampler-ratio", "0.5", "tracing-compression", TracingOptions.TracingCompression.gzip.name(), + "tracing-service-name", "keycloak-42", + "tracing-resource-attributes", "host.name=unknown,service.version=30" + )); + assertConfig(Map.of( "log-console-include-trace", "false", "log-file-include-trace", "false", "log-syslog-include-trace", "false" @@ -92,10 +102,49 @@ public class TracingConfigurationTest extends AbstractConfigurationTest { "quarkus.datasource.jdbc.telemetry", "false", "quarkus.otel.traces.sampler", SamplerType.PARENT_BASED_ALWAYS_ON.getValue(), "quarkus.otel.traces.sampler.arg", "0.5", - "quarkus.otel.exporter.otlp.traces.compression", TracingOptions.TracingCompression.gzip.name() + "quarkus.otel.exporter.otlp.traces.compression", TracingOptions.TracingCompression.gzip.name(), + "quarkus.otel.service.name", "keycloak-42", + "quarkus.otel.resource.attributes", "host.name=unknown,service.version=30" )); } + @Test + public void serviceNamePreference() { + putEnvVars(Map.of( + "KC_TRACING_ENABLED", "true", + "KC_TRACING_SERVICE_NAME", "service-name", + "KC_TRACING_RESOURCE_ATTRIBUTES", "service.name=new-service-name" + )); + + initConfig(); + + assertConfig(Map.of( + "tracing-enabled", "true", + "tracing-service-name", "service-name", + "tracing-resource-attributes", "service.name=new-service-name" + )); + + assertExternalConfig("quarkus.otel.service.name", "service-name"); + } + + @Test + public void serviceNameResourceAttributes() { + putEnvVars(Map.of( + "KC_TRACING_ENABLED", "true", + "KC_TRACING_RESOURCE_ATTRIBUTES", "service.name=new-service-name" + )); + + initConfig(); + + assertConfig(Map.of( + "tracing-enabled", "true", + "tracing-resource-attributes", "service.name=new-service-name" + )); + + // the default value should be used + assertExternalConfig("quarkus.otel.service.name", "keycloak"); + } + @Test public void consoleLogTraceOn() { assertLogFormat(LoggingOptions.Handler.console, true, LoggingOptions.DEFAULT_LOG_TRACING_FORMAT); diff --git a/quarkus/tests/integration/src/test/java/org/keycloak/it/cli/dist/TracingDistTest.java b/quarkus/tests/integration/src/test/java/org/keycloak/it/cli/dist/TracingDistTest.java index 92916a609b..0488197562 100644 --- a/quarkus/tests/integration/src/test/java/org/keycloak/it/cli/dist/TracingDistTest.java +++ b/quarkus/tests/integration/src/test/java/org/keycloak/it/cli/dist/TracingDistTest.java @@ -34,12 +34,12 @@ public class TracingDistTest { private void assertTracingEnabled(CLIResult result) { result.assertMessage("opentelemetry"); - result.assertMessage("service.name=\"Keycloak\""); + result.assertMessage("service.name=\"keycloak\""); } private void assertTracingDisabled(CLIResult result) { result.assertMessage("opentelemetry"); - result.assertNoMessage("service.name=\"Keycloak\""); + result.assertNoMessage("service.name=\"keycloak\""); result.assertNoMessage("Failed to export spans."); result.assertNoMessage("Connection refused: localhost/127.0.0.1:4317"); } @@ -63,7 +63,6 @@ public class TracingDistTest { cliResult.assertStartedDevMode(); assertTracingEnabled(cliResult); } - @Test @Order(3) @Launch({"build", "--tracing-enabled=true"}) @@ -150,4 +149,39 @@ public class TracingDistTest { cliResult.assertNoMessage("traceId=, parentId=, spanId=, sampled="); cliResult.assertStarted(); } + + @Test + @Launch({"start", "--hostname-strict=false", "--http-enabled=true", "--optimized", "--log-level=io.opentelemetry:fine", "--tracing-service-name=my-service"}) + void differentServiceName(LaunchResult result) { + CLIResult cliResult = (CLIResult) result; + + cliResult.assertMessage("opentelemetry"); + cliResult.assertMessage("service.name=\"my-service\""); + + cliResult.assertStarted(); + } + + @Test + @Launch({"start", "--hostname-strict=false", "--http-enabled=true", "--optimized", "--log-level=io.opentelemetry:fine", "--tracing-resource-attributes=service.name=new-service"}) + void serviceNameResourceAttributes(LaunchResult result) { + CLIResult cliResult = (CLIResult) result; + + // the default value should be used + assertTracingEnabled(cliResult); + + cliResult.assertStarted(); + } + + @Test + @Launch({"start", "--hostname-strict=false", "--http-enabled=true", "--optimized", "--log-level=io.opentelemetry:fine", "--tracing-resource-attributes=some.key1=some.val1,some.key2=some.val2",}) + void resourceAttributes(LaunchResult result) { + CLIResult cliResult = (CLIResult) result; + + assertTracingEnabled(cliResult); + + cliResult.assertMessage("some.key1=\"some.val1\""); + cliResult.assertMessage("some.key2=\"some.val2\""); + + cliResult.assertStarted(); + } } diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testExportHelpAll.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testExportHelpAll.approved.txt index 2b43eae2a9..87476536fc 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testExportHelpAll.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testExportHelpAll.approved.txt @@ -219,6 +219,11 @@ Tracing (Preview): Preview: OpenTelemetry protocol used for the telemetry data. Possible values are: grpc, http/protobuf. Default: grpc. Available only when Tracing is enabled. +--tracing-resource-attributes + Preview: OpenTelemetry resource attributes present in the exported trace to + characterize the telemetry producer. Values in format 'key1=val1,key2=val2'. + For more information, check the Tracing guide. Available only when Tracing + is enabled. --tracing-sampler-ratio Preview: OpenTelemetry sampler ratio. Probability that a span will be sampled. Expected double value in interval <0,1). Default: 1.0. Available only when @@ -228,6 +233,10 @@ Tracing (Preview): always_on, always_off, traceidratio, parentbased_always_on, parentbased_always_off, parentbased_traceidratio. Default: traceidratio. Available only when Tracing is enabled. +--tracing-service-name + Preview: OpenTelemetry service name. Takes precedence over 'service.name' + defined in the 'tracing-resource-attributes' property. Default: keycloak. + Available only when Tracing is enabled. Truststore: diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testImportHelpAll.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testImportHelpAll.approved.txt index 11b908daa0..5a47dbbd3b 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testImportHelpAll.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testImportHelpAll.approved.txt @@ -219,6 +219,11 @@ Tracing (Preview): Preview: OpenTelemetry protocol used for the telemetry data. Possible values are: grpc, http/protobuf. Default: grpc. Available only when Tracing is enabled. +--tracing-resource-attributes + Preview: OpenTelemetry resource attributes present in the exported trace to + characterize the telemetry producer. Values in format 'key1=val1,key2=val2'. + For more information, check the Tracing guide. Available only when Tracing + is enabled. --tracing-sampler-ratio Preview: OpenTelemetry sampler ratio. Probability that a span will be sampled. Expected double value in interval <0,1). Default: 1.0. Available only when @@ -228,6 +233,10 @@ Tracing (Preview): always_on, always_off, traceidratio, parentbased_always_on, parentbased_always_off, parentbased_traceidratio. Default: traceidratio. Available only when Tracing is enabled. +--tracing-service-name + Preview: OpenTelemetry service name. Takes precedence over 'service.name' + defined in the 'tracing-resource-attributes' property. Default: keycloak. + Available only when Tracing is enabled. Truststore: diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelpAll.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelpAll.approved.txt index 5f4fe9b184..219e41e586 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelpAll.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelpAll.approved.txt @@ -430,6 +430,11 @@ Tracing (Preview): Preview: OpenTelemetry protocol used for the telemetry data. Possible values are: grpc, http/protobuf. Default: grpc. Available only when Tracing is enabled. +--tracing-resource-attributes + Preview: OpenTelemetry resource attributes present in the exported trace to + characterize the telemetry producer. Values in format 'key1=val1,key2=val2'. + For more information, check the Tracing guide. Available only when Tracing + is enabled. --tracing-sampler-ratio Preview: OpenTelemetry sampler ratio. Probability that a span will be sampled. Expected double value in interval <0,1). Default: 1.0. Available only when @@ -439,6 +444,10 @@ Tracing (Preview): always_on, always_off, traceidratio, parentbased_always_on, parentbased_always_off, parentbased_traceidratio. Default: traceidratio. Available only when Tracing is enabled. +--tracing-service-name + Preview: OpenTelemetry service name. Takes precedence over 'service.name' + defined in the 'tracing-resource-attributes' property. Default: keycloak. + Available only when Tracing is enabled. Truststore: diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelpAll.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelpAll.approved.txt index 7e22edbd08..3e2150f6ed 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelpAll.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelpAll.approved.txt @@ -431,6 +431,11 @@ Tracing (Preview): Preview: OpenTelemetry protocol used for the telemetry data. Possible values are: grpc, http/protobuf. Default: grpc. Available only when Tracing is enabled. +--tracing-resource-attributes + Preview: OpenTelemetry resource attributes present in the exported trace to + characterize the telemetry producer. Values in format 'key1=val1,key2=val2'. + For more information, check the Tracing guide. Available only when Tracing + is enabled. --tracing-sampler-ratio Preview: OpenTelemetry sampler ratio. Probability that a span will be sampled. Expected double value in interval <0,1). Default: 1.0. Available only when @@ -440,6 +445,10 @@ Tracing (Preview): always_on, always_off, traceidratio, parentbased_always_on, parentbased_always_off, parentbased_traceidratio. Default: traceidratio. Available only when Tracing is enabled. +--tracing-service-name + Preview: OpenTelemetry service name. Takes precedence over 'service.name' + defined in the 'tracing-resource-attributes' property. Default: keycloak. + Available only when Tracing is enabled. Truststore: diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelpAll.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelpAll.approved.txt index 600b4ba02e..2c4149899b 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelpAll.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelpAll.approved.txt @@ -377,10 +377,19 @@ Tracing (Preview): Preview: OpenTelemetry protocol used for the telemetry data. Possible values are: grpc, http/protobuf. Default: grpc. Available only when Tracing is enabled. +--tracing-resource-attributes + Preview: OpenTelemetry resource attributes present in the exported trace to + characterize the telemetry producer. Values in format 'key1=val1,key2=val2'. + For more information, check the Tracing guide. Available only when Tracing + is enabled. --tracing-sampler-ratio Preview: OpenTelemetry sampler ratio. Probability that a span will be sampled. Expected double value in interval <0,1). Default: 1.0. Available only when Tracing is enabled. +--tracing-service-name + Preview: OpenTelemetry service name. Takes precedence over 'service.name' + defined in the 'tracing-resource-attributes' property. Default: keycloak. + Available only when Tracing is enabled. Truststore: