From 402a04761236b6e88d845648223d6d42ad2009bc Mon Sep 17 00:00:00 2001 From: Emily Jiang Date: Mon, 19 Feb 2024 14:20:01 +0000 Subject: [PATCH 1/3] add logs --- spec/src/main/asciidoc/logs.adoc | 43 +++++++++++++++++++ .../microprofile-telemetry-spec.asciidoc | 1 + .../src/main/asciidoc/opentelemetry-apis.adoc | 8 +--- 3 files changed, 46 insertions(+), 6 deletions(-) create mode 100644 spec/src/main/asciidoc/logs.adoc diff --git a/spec/src/main/asciidoc/logs.adoc b/spec/src/main/asciidoc/logs.adoc new file mode 100644 index 00000000..0b855ca7 --- /dev/null +++ b/spec/src/main/asciidoc/logs.adoc @@ -0,0 +1,43 @@ +// +// Copyright (c) 2024 Contributors to the Eclipse Foundation +// +// See the NOTICE file(s) distributed with this work for additional +// information regarding copyright ownership. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +[[logs]] +== Logs +The OpenTelemetry Logs bridge API exists to enable bridging logs from other log frameworks (e.g. SLF4J, Log4j, JUL, Logback, etc) into OpenTelemetry. It does not define new Log APIs. The following shows the entry points. + +[source,java] +---- +LoggerProvider (provider.loggerBuilder(instrumentationScopeName) + -> LoggerBuilder (loggerBuilder.build()) + ->Logger (logger.logRecordBuilder) + ->LogRecordBuilder +---- + +=== Access to the OpenTelemetry Logs API +An implementation of MicroProfile Telemetry Logs MUST provide the following CDI beans for supporting contextual instance injection: + +* `io.opentelemetry.api.logs.LoggerProvider` + +[source,java] +---- +@Inject LoggerProvider provider; +---- + + + diff --git a/spec/src/main/asciidoc/microprofile-telemetry-spec.asciidoc b/spec/src/main/asciidoc/microprofile-telemetry-spec.asciidoc index 1e5237bc..9b28e581 100644 --- a/spec/src/main/asciidoc/microprofile-telemetry-spec.asciidoc +++ b/spec/src/main/asciidoc/microprofile-telemetry-spec.asciidoc @@ -44,6 +44,7 @@ include::introduction.adoc[] include::integration.adoc[] include::tracing.adoc[] include::metrics.adoc[] +include::logs.adoc[] include::configuration.adoc[] include::opentelemetry-apis.adoc[] include::release-notes.adoc[] diff --git a/spec/src/main/asciidoc/opentelemetry-apis.adoc b/spec/src/main/asciidoc/opentelemetry-apis.adoc index fe51b1cb..09b2e67c 100644 --- a/spec/src/main/asciidoc/opentelemetry-apis.adoc +++ b/spec/src/main/asciidoc/opentelemetry-apis.adoc @@ -35,12 +35,8 @@ Baggage API:: * https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/baggage/propagation/package-summary.html[io.opentelemetry.api.baggage.propagation] Metrics API:: * https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/metrics/package-summary.html[io.opentelemetry.api.metrics] - - -[NOTE] -===== -`io.opentelemetry.api` does depend on https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/logs/package-summary.html[io.opentelemetry.api.logs], though this specification only supports the parts that relate to Tracing and Metrics. -===== +Logs API:: +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/logs/package-summary.html[io.opentelemetry.api.logs] === Context API From 5ade2415ccce3a192c17c0625fa362db47286451 Mon Sep 17 00:00:00 2001 From: Emily Jiang Date: Mon, 11 Mar 2024 23:32:55 +0000 Subject: [PATCH 2/3] update --- spec/src/main/asciidoc/configuration.adoc | 78 ++++++++++++++++++++++- spec/src/main/asciidoc/logs.adoc | 23 +------ 2 files changed, 78 insertions(+), 23 deletions(-) diff --git a/spec/src/main/asciidoc/configuration.adoc b/spec/src/main/asciidoc/configuration.adoc index 1a312762..a9c72f6c 100644 --- a/spec/src/main/asciidoc/configuration.adoc +++ b/spec/src/main/asciidoc/configuration.adoc @@ -51,6 +51,13 @@ Values other than `none` and `otlp` might link:#sec:service-loader-support[requi Default value: `otlp` +|`otel.logs.exporter` +| List of exporters to be used for logs, separated by commas. +`none` means no autoconfigured exporter. +Values other than `none` and `otlp` might link:#sec:service-loader-support[require additional libraries] + +Default value: `otlp` + | `otel.propagators` | The propagators to be used. Values other than `none`, `tracecontext` and `baggage` might link:#sec:service-loader-support[require additional libraries] @@ -180,9 +187,31 @@ Default value: `TRACE_BASED` | `otel.metric.export.interval` | The interval, in milliseconds, between the start of two export attempts. -Default value: `60000` +2+h| Batch log record processor + +| `otel.blrp.schedule.delay` +| The interval, in milliseconds, between two consecutive exports. + +Default value: `1000` + +| `otel.blrp.max.queue.size` +| The maximum batch size. + +Default value: `512` + +| `otel.blrp.max.export.batch.size` +| The maximum queue size. + +Default value: `2048` + +| `otel.blrp.export.timeout` +| The maximum allowed time, in milliseconds, to export data. + +Default value: `30000` + |=== + If Environment Config Source is enabled for MicroProfile Config, then the environment variables as described by the OpenTelemetry SDK Autoconfigure are also supported. === Optional Configuration Properties @@ -207,6 +236,12 @@ Options include grpc and http/protobuf. Default value: `grpc` +| `otel.exporter.otlp.logs.protocol` +| The transport protocol to use on OTLP log requests. +Options include grpc and http/protobuf. + +Default value: `grpc` + | `otel.exporter.otlp.traces.endpoint` | The OTLP traces endpoint to connect to. MUST be a URL with a scheme of either http or https based on the use of TLS. @@ -219,6 +254,12 @@ MUST be a URL with a scheme of either http or https based on the use of TLS. Default value: `http://localhost:4317` when protocol is `grpc`, and `http://localhost:4318/v1/metrics` when protocol is `http/protobuf` +| `otel.exporter.otlp.logs.endpoint` +| The OTLP logs endpoint to connect to. +MUST be a URL with a scheme of either http or https based on the use of TLS. + +Default value: `http://localhost:4317` when protocol is `grpc`, and `http://localhost:4318/v1/logs` when protocol is `http/protobuf` + | `otel.exporter.otlp.traces.certificate` | The path to the file containing trusted certificates to use when verifying an OTLP trace server's TLS credentials. The file SHOULD contain one or more X.509 certificates in PEM format. @@ -231,6 +272,12 @@ The file SHOULD contain one or more X.509 certificates in PEM format. By default the host platform's trusted root certificates are used. +| `otel.exporter.otlp.logs.certificate` +| The path to the file containing trusted certificates to use when verifying an OTLP log server's TLS credentials. +The file SHOULD contain one or more X.509 certificates in PEM format. + +By default the host platform's trusted root certificates are used. + | `otel.exporter.otlp.traces.client.key` | The path to the file containing private client key to use when verifying an OTLP trace client's TLS credentials. The file SHOULD contain one private key PKCS8 PEM format. @@ -243,6 +290,12 @@ The file SHOULD contain one private key PKCS8 PEM format. By default no client key file is used. +| `otel.exporter.otlp.logs.client.key` +| The path to the file containing private client key to use when verifying an OTLP log client's TLS credentials. +The file SHOULD contain one private key PKCS8 PEM format. + +By default no client key file is used. + | `otel.exporter.otlp.traces.client.certificate` | The path to the file containing trusted certificates to use when verifying an OTLP trace server's TLS credentials. The file SHOULD contain one or more X.509 certificates in PEM format. @@ -255,12 +308,21 @@ The file SHOULD contain one or more X.509 certificates in PEM format. By default no chain file is used. +| `otel.exporter.otlp.logs.client.certificate` +| The path to the file containing trusted certificates to use when verifying an OTLP log server's TLS credentials. +The file SHOULD contain one or more X.509 certificates in PEM format. + +By default no chain file is used. + | `otel.exporter.otlp.traces.headers` | Key-value pairs separated by commas to pass as request headers on OTLP trace requests. | `otel.exporter.otlp.metrics.headers` | Key-value pairs separated by commas to pass as request headers on OTLP metric requests. +| `otel.exporter.otlp.logs.headers` +| Key-value pairs separated by commas to pass as request headers on OTLP log requests. + | `otel.exporter.otlp.traces.compression` | The compression type to use on OTLP trace requests. Options include `gzip`. @@ -273,6 +335,12 @@ Options include `gzip`. By default no compression will be used. +| `otel.exporter.otlp.logs.compression` +| The compression type to use on OTLP log requests. +Options include `gzip`. + +By default no compression will be used. + | `otel.exporter.otlp.traces.timeout` | The maximum waiting time, in milliseconds, allowed to send each OTLP trace batch. @@ -283,6 +351,11 @@ Default value: `10000` Default value: `10000` +| `otel.exporter.otlp.logs.timeout` +| The maximum waiting time, in milliseconds, allowed to send each OTLP log batch. + +Default value: `10000` + |=== [[sec:service-loader-support]] @@ -313,6 +386,9 @@ The following components are supported | https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/metrics/ConfigurableMetricExporterProvider.html[`ConfigurableMetricExporterProvider`] | Provides implementation for a name referred in `otel.metrics.exporter` + +| https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/logs/ConfigurableLogRecordExporterProvider.html[`ConfigurableLogRecordExporterProvider`] +| Provides implementation for a name referred in `otel.logs.exporter` |=== Behavior when multiple implementations are found for a given component name is undefined. diff --git a/spec/src/main/asciidoc/logs.adoc b/spec/src/main/asciidoc/logs.adoc index 0b855ca7..c8bc1613 100644 --- a/spec/src/main/asciidoc/logs.adoc +++ b/spec/src/main/asciidoc/logs.adoc @@ -19,25 +19,4 @@ [[logs]] == Logs -The OpenTelemetry Logs bridge API exists to enable bridging logs from other log frameworks (e.g. SLF4J, Log4j, JUL, Logback, etc) into OpenTelemetry. It does not define new Log APIs. The following shows the entry points. - -[source,java] ----- -LoggerProvider (provider.loggerBuilder(instrumentationScopeName) - -> LoggerBuilder (loggerBuilder.build()) - ->Logger (logger.logRecordBuilder) - ->LogRecordBuilder ----- - -=== Access to the OpenTelemetry Logs API -An implementation of MicroProfile Telemetry Logs MUST provide the following CDI beans for supporting contextual instance injection: - -* `io.opentelemetry.api.logs.LoggerProvider` - -[source,java] ----- -@Inject LoggerProvider provider; ----- - - - +The OpenTelemetry Logs bridge API exists to enable bridging logs from other log frameworks (e.g. SLF4J, Log4j, JUL, Logback, etc) into OpenTelemetry. It does not define new Log APIs and the Logs bridge APIs in OpenTelemetry are not for application but for runtime to bridge log frameworks. Therefore, this specification does not expose any Log APIs. \ No newline at end of file From 8e816c9fc679ce584d68adea20d159d2b43b2ee8 Mon Sep 17 00:00:00 2001 From: Emily Jiang Date: Wed, 27 Mar 2024 23:31:16 +0000 Subject: [PATCH 3/3] minor update --- spec/src/main/asciidoc/configuration.adoc | 1 + spec/src/main/asciidoc/opentelemetry-apis.adoc | 2 -- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/spec/src/main/asciidoc/configuration.adoc b/spec/src/main/asciidoc/configuration.adoc index a9c72f6c..1045b9c9 100644 --- a/spec/src/main/asciidoc/configuration.adoc +++ b/spec/src/main/asciidoc/configuration.adoc @@ -47,6 +47,7 @@ Default value: `otlp` |`otel.metrics.exporter` | List of exporters to be used for metrics, separated by commas. +`none` means no autoconfigured exporter. Values other than `none` and `otlp` might link:#sec:service-loader-support[require additional libraries] Default value: `otlp` diff --git a/spec/src/main/asciidoc/opentelemetry-apis.adoc b/spec/src/main/asciidoc/opentelemetry-apis.adoc index 09b2e67c..a4ad6a2e 100644 --- a/spec/src/main/asciidoc/opentelemetry-apis.adoc +++ b/spec/src/main/asciidoc/opentelemetry-apis.adoc @@ -35,8 +35,6 @@ Baggage API:: * https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/baggage/propagation/package-summary.html[io.opentelemetry.api.baggage.propagation] Metrics API:: * https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/metrics/package-summary.html[io.opentelemetry.api.metrics] -Logs API:: -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/logs/package-summary.html[io.opentelemetry.api.logs] === Context API