From ab42bd437e18171b3f25a2c6805d4f71e3ce30a3 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 18 Oct 2023 13:37:13 -0700 Subject: [PATCH 01/13] Define OT1000 & OT1001 diagnostics and decorate APIs in OpenTelemetry.Api using .NET8 ExperimentalAttribute. --- OpenTelemetry.sln | 9 +++- build/Common.props | 2 + docs/diagnostics/OT1000.md | 42 +++++++++++++++++++ docs/diagnostics/OT1001.md | 34 +++++++++++++++ docs/metrics/exemplars/docker-compose.yaml | 5 ++- .../Logs/IDeferredLoggerProviderBuilder.cs | 9 +++- .../Logs/LogRecordAttributeList.cs | 6 +++ src/OpenTelemetry.Api/Logs/LogRecordData.cs | 6 +++ .../Logs/LogRecordSeverity.cs | 7 ++++ .../Logs/LogRecordSeverityExtensions.cs | 7 ++++ src/OpenTelemetry.Api/Logs/Logger.cs | 9 +++- src/OpenTelemetry.Api/Logs/LoggerProvider.cs | 15 +++++++ .../Logs/LoggerProviderBuilder.cs | 7 ++++ 13 files changed, 153 insertions(+), 5 deletions(-) create mode 100644 docs/diagnostics/OT1000.md create mode 100644 docs/diagnostics/OT1001.md diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index 922ba6b2d20..f43ac30b6f6 100644 --- a/OpenTelemetry.sln +++ b/OpenTelemetry.sln @@ -90,8 +90,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "ISSUE_TEMPLATE", "ISSUE_TEM EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "workflows", "workflows", "{E69578EB-B456-4062-A645-877CD964528B}" ProjectSection(SolutionItems) = preProject - .github\workflows\ci-aot.yml = .github\workflows\ci-aot.yml .github\workflows\ci-aot-md.yml = .github\workflows\ci-aot-md.yml + .github\workflows\ci-aot.yml = .github\workflows\ci-aot.yml .github\workflows\ci-instrumentation-libraries-md.yml = .github\workflows\ci-instrumentation-libraries-md.yml .github\workflows\ci-instrumentation-libraries.yml = .github\workflows\ci-instrumentation-libraries.yml .github\workflows\ci-md.yml = .github\workflows\ci-md.yml @@ -315,6 +315,12 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Metrics", "Metrics", "{1C45 EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "getting-started-aspnetcore", "docs\logs\getting-started-aspnetcore\getting-started-aspnetcore.csproj", "{99B4D965-8782-4694-8DFA-B7A3630CEF60}" EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "diagnostics", "diagnostics", "{52AF6D7D-9E66-4234-9A2C-5D16C6F22B40}" + ProjectSection(SolutionItems) = preProject + docs\diagnostics\OT1000.md = docs\diagnostics\OT1000.md + docs\diagnostics\OT1001.md = docs\diagnostics\OT1001.md + EndProjectSection +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -637,6 +643,7 @@ Global {A0CB9A10-F22D-4E66-A449-74B3D0361A9C} = {A49299FB-C5CD-4E0E-B7E1-B7867BBD67CC} {1C459B5B-C702-46FF-BF1A-EE795E420FFA} = {A49299FB-C5CD-4E0E-B7E1-B7867BBD67CC} {99B4D965-8782-4694-8DFA-B7A3630CEF60} = {3862190B-E2C5-418E-AFDC-DB281FB5C705} + {52AF6D7D-9E66-4234-9A2C-5D16C6F22B40} = {7C87CAF9-79D7-4C26-9FFB-F3F1FB6911F1} EndGlobalSection GlobalSection(ExtensibilityGlobals) = postSolution SolutionGuid = {55639B5C-0770-4A22-AB56-859604650521} diff --git a/build/Common.props b/build/Common.props index 569dd2f5a52..31037f59177 100644 --- a/build/Common.props +++ b/build/Common.props @@ -9,6 +9,8 @@ true enable enable + + $(NoWarn);OT1000;OT1001 diff --git a/docs/diagnostics/OT1000.md b/docs/diagnostics/OT1000.md new file mode 100644 index 00000000000..65041af3441 --- /dev/null +++ b/docs/diagnostics/OT1000.md @@ -0,0 +1,42 @@ +# OpenTelemetry .NET Diagnostic: OT1000 + +## Overview + +This is an experimental feature diagnostic covering the following APIs: + +* `LoggerProviderBuilder` +* `LoggerProvider` +* `IDeferredLoggerProviderBuilder` + +Experimental features may be changed or removed in the future. + +## Details + +The OpenTelemetry Specification defines a `LoggerProvider` as part of its +[API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md) +& +[SDK](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/sdk.md) +components. + +The SDK allows calling `Shutdown` and `ForceFlush` on the `LoggerProvider` and +also allows processors to be added dynamically to a pipeline after its creation. + +Today the OpenTelemetry .NET log pipeline is built on top of the +Microsoft.Extensions.Logging `ILogger` \ `ILoggerProvider` \ `ILoggerFactory` +APIs which do not expose such features. + +We also have an issue with the `ILoggingBuilder.AddOpenTelemetry` API in that it +interacts with the `OpenTelemetryLoggerOptions` class. Options classes are NOT +available until the `IServiceProvider` is available and services can no longer +be registered at that point. This prevents the current logging pipeline from +exposing the same dependency injection surface we have for traces and metrics. + +We are exposing these APIs to solve these issues and gather feedback about their +usefulness. + +## Log Bride API + +The OpenTelemetry Specification defines a log bridge API which is rooted off of +the `LoggerProvider` (`GetLogger`) and exposes a `Logger` API to submit log +records. See [OT1001](.\OT1001.md) for details about the log bridge +implementation status. diff --git a/docs/diagnostics/OT1001.md b/docs/diagnostics/OT1001.md new file mode 100644 index 00000000000..ae92cd6d548 --- /dev/null +++ b/docs/diagnostics/OT1001.md @@ -0,0 +1,34 @@ +# OpenTelemetry .NET Diagnostic: OT1001 + +## Overview + +This is an experimental feature diagnostic covering the following APIs: + +* `LoggerProvider.GetLogger` +* `Logger` +* `LogRecordAttributeList` +* `LogRecordData` +* `LogRecordSeverity` + +Experimental features may be changed or removed in the future. + +## Details + +The OpenTelemetry Specification defines a [Logs Bridge +API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md). + +The log bridge API is used by library authors to build log appenders which route +messages from different log frameworks into OpenTelemetry. + +Today the OpenTelemetry .NET log pipeline is built on top of the +Microsoft.Extensions.Logging `ILogger` \ `ILoggerProvider` \ `ILoggerFactory` +APIs. + +We are exposing these APIs gather feedback about their usefulness. An +alternative approach may be taken which would be to append into `ILogger` +instead of OpenTelemetry directly. + +## LoggerProvider API + +The OpenTelemetry Specification defines a `LoggerProvider` API. See +[OT1000](.\OT1001.md) for details about the log implementation status. diff --git a/docs/metrics/exemplars/docker-compose.yaml b/docs/metrics/exemplars/docker-compose.yaml index 87cd7a6c6d6..fa9966c6d8a 100644 --- a/docs/metrics/exemplars/docker-compose.yaml +++ b/docs/metrics/exemplars/docker-compose.yaml @@ -3,7 +3,7 @@ services: # OTEL Collector to receive logs, metrics and traces from the application otel-collector: - image: otel/opentelemetry-collector:0.70.0 + image: otel/opentelemetry-collector:latest command: [ "--config=/etc/otel-collector.yaml" ] volumes: - ./otel-collector.yaml:/etc/otel-collector.yaml @@ -31,6 +31,7 @@ services: - --config.file=/etc/prometheus.yaml - --web.enable-remote-write-receiver - --enable-feature=exemplar-storage + - --log.level=debug volumes: - ./prometheus.yaml:/etc/prometheus.yaml ports: @@ -38,7 +39,7 @@ services: # UI to query traces and metrics grafana: - image: grafana/grafana:9.3.2 + image: grafana/grafana:latest volumes: - ./grafana-datasources.yaml:/etc/grafana/provisioning/datasources/datasources.yaml environment: diff --git a/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs b/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs index cf6852327ac..828b2f4e1ae 100644 --- a/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs +++ b/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs @@ -16,6 +16,10 @@ #nullable enable +#if NET8_0_OR_GREATER +using System.Diagnostics.CodeAnalysis; +#endif + namespace OpenTelemetry.Logs; #if EXPOSE_EXPERIMENTAL_FEATURES @@ -25,6 +29,9 @@ namespace OpenTelemetry.Logs; /// dependency injection. /// /// +#if NET8_0_OR_GREATER +[Experimental("OT1000", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +#endif public #else /// @@ -34,7 +41,7 @@ namespace OpenTelemetry.Logs; /// internal #endif - interface IDeferredLoggerProviderBuilder +interface IDeferredLoggerProviderBuilder { /// /// Register a callback action to configure the /// +#if NET8_0_OR_GREATER +[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +#endif public #else /// diff --git a/src/OpenTelemetry.Api/Logs/LogRecordData.cs b/src/OpenTelemetry.Api/Logs/LogRecordData.cs index 37225cb3e74..6c7ff525b5f 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordData.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordData.cs @@ -17,6 +17,9 @@ #nullable enable using System.Diagnostics; +#if NET8_0_OR_GREATER +using System.Diagnostics.CodeAnalysis; +#endif namespace OpenTelemetry.Logs; @@ -25,6 +28,9 @@ namespace OpenTelemetry.Logs; /// Stores details about a log message. /// /// +#if NET8_0_OR_GREATER +[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +#endif public #else /// diff --git a/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs b/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs index 3fc9a7aa660..d552c0f7b0d 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs @@ -16,6 +16,10 @@ #nullable enable +#if NET8_0_OR_GREATER +using System.Diagnostics.CodeAnalysis; +#endif + namespace OpenTelemetry.Logs; #if EXPOSE_EXPERIMENTAL_FEATURES @@ -23,6 +27,9 @@ namespace OpenTelemetry.Logs; /// Describes the severity level of a log record. /// /// +#if NET8_0_OR_GREATER +[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +#endif public #else /// diff --git a/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs b/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs index 0a9556e4b6a..13336d5602d 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs @@ -16,6 +16,10 @@ #nullable enable +#if NET8_0_OR_GREATER +using System.Diagnostics.CodeAnalysis; +#endif + namespace OpenTelemetry.Logs; #if EXPOSE_EXPERIMENTAL_FEATURES @@ -23,6 +27,9 @@ namespace OpenTelemetry.Logs; /// Contains extension methods for the enum. /// /// +#if NET8_0_OR_GREATER +[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +#endif public #else /// diff --git a/src/OpenTelemetry.Api/Logs/Logger.cs b/src/OpenTelemetry.Api/Logs/Logger.cs index 17297a977f1..838105bc400 100644 --- a/src/OpenTelemetry.Api/Logs/Logger.cs +++ b/src/OpenTelemetry.Api/Logs/Logger.cs @@ -16,6 +16,10 @@ #nullable enable +#if NET8_0_OR_GREATER +using System.Diagnostics.CodeAnalysis; +#endif + namespace OpenTelemetry.Logs; #if EXPOSE_EXPERIMENTAL_FEATURES @@ -23,6 +27,9 @@ namespace OpenTelemetry.Logs; /// Logger is the class responsible for creating log records. /// /// WARNING: This is an experimental API which might change or be removed in the future. Use at your own risk. +#if NET8_0_OR_GREATER +[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +#endif public #else /// @@ -30,7 +37,7 @@ namespace OpenTelemetry.Logs; /// internal #endif - abstract class Logger +abstract class Logger { /// /// Initializes a new instance of the class. diff --git a/src/OpenTelemetry.Api/Logs/LoggerProvider.cs b/src/OpenTelemetry.Api/Logs/LoggerProvider.cs index 405ea7e12ac..01dafceb98c 100644 --- a/src/OpenTelemetry.Api/Logs/LoggerProvider.cs +++ b/src/OpenTelemetry.Api/Logs/LoggerProvider.cs @@ -27,6 +27,9 @@ namespace OpenTelemetry.Logs; /// LoggerProvider is the entry point of the OpenTelemetry API. It provides access to . /// /// +#if NET8_0_OR_GREATER +[Experimental("OT1000", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +#endif public #else /// @@ -49,6 +52,9 @@ protected LoggerProvider() /// Gets a logger. /// /// instance. +#if NET8_0_OR_GREATER + [Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +#endif public Logger GetLogger() => this.GetLogger(name: null, version: null); @@ -57,6 +63,9 @@ public Logger GetLogger() /// /// Optional name identifying the instrumentation library. /// instance. +#if NET8_0_OR_GREATER + [Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +#endif public Logger GetLogger(string? name) => this.GetLogger(name, version: null); @@ -66,6 +75,9 @@ public Logger GetLogger(string? name) /// Optional name identifying the instrumentation library. /// Optional version of the instrumentation library. /// instance. +#if NET8_0_OR_GREATER + [Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +#endif public Logger GetLogger(string? name, string? version) { if (!this.TryCreateLogger(name, out var logger)) @@ -84,6 +96,9 @@ public Logger GetLogger(string? name, string? version) /// Optional name identifying the instrumentation library. /// . /// if the logger was created. +#if NET8_0_OR_GREATER + [Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +#endif protected virtual bool TryCreateLogger( string? name, #if NETSTANDARD2_1_OR_GREATER || NET6_0_OR_GREATER diff --git a/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs b/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs index a460e6e2598..9373fe836a5 100644 --- a/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs +++ b/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs @@ -16,6 +16,10 @@ #nullable enable +#if NET8_0_OR_GREATER +using System.Diagnostics.CodeAnalysis; +#endif + namespace OpenTelemetry.Logs; #if EXPOSE_EXPERIMENTAL_FEATURES @@ -23,6 +27,9 @@ namespace OpenTelemetry.Logs; /// LoggerProviderBuilder base class. /// /// +#if NET8_0_OR_GREATER +[Experimental("OT1000", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +#endif public #else /// From 87361d61cdebcc5f15b242cfc8e82cb5eacafc5e Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 18 Oct 2023 14:34:31 -0700 Subject: [PATCH 02/13] Revert accidental changes. --- docs/metrics/exemplars/docker-compose.yaml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/metrics/exemplars/docker-compose.yaml b/docs/metrics/exemplars/docker-compose.yaml index fa9966c6d8a..c8cc94fa4b1 100644 --- a/docs/metrics/exemplars/docker-compose.yaml +++ b/docs/metrics/exemplars/docker-compose.yaml @@ -3,7 +3,7 @@ services: # OTEL Collector to receive logs, metrics and traces from the application otel-collector: - image: otel/opentelemetry-collector:latest + image: otel/opentelemetry-collector:0.70.0 command: [ "--config=/etc/otel-collector.yaml" ] volumes: - ./otel-collector.yaml:/etc/otel-collector.yaml @@ -31,7 +31,6 @@ services: - --config.file=/etc/prometheus.yaml - --web.enable-remote-write-receiver - --enable-feature=exemplar-storage - - --log.level=debug volumes: - ./prometheus.yaml:/etc/prometheus.yaml ports: @@ -39,7 +38,7 @@ services: # UI to query traces and metrics grafana: - image: grafana/grafana:latest + image: grafana/grafana:9.3.2 volumes: - ./grafana-datasources.yaml:/etc/grafana/provisioning/datasources/datasources.yaml environment: @@ -49,4 +48,3 @@ services: - GF_FEATURE_TOGGLES_ENABLE=traceqlEditor ports: - "3000:3000" - From 8ccc64f978aa8186b3a4e3075ceb5abe23c18720 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 1 Nov 2023 15:42:41 -0700 Subject: [PATCH 03/13] Code review. --- OpenTelemetry.sln | 5 ++-- build/Common.props | 2 +- docs/diagnostics/{OT1000.md => OTEL1000.md} | 4 +-- docs/diagnostics/{OT1001.md => OTEL1001.md} | 4 +-- .../Logs/IDeferredLoggerProviderBuilder.cs | 3 ++- .../Logs/LogRecordAttributeList.cs | 2 +- src/OpenTelemetry.Api/Logs/LogRecordData.cs | 3 ++- .../Logs/LogRecordSeverity.cs | 3 ++- .../Logs/LogRecordSeverityExtensions.cs | 3 ++- src/OpenTelemetry.Api/Logs/Logger.cs | 3 ++- src/OpenTelemetry.Api/Logs/LoggerProvider.cs | 11 ++++---- .../Logs/LoggerProviderBuilder.cs | 3 ++- .../OpenTelemetry.Api.csproj | 1 + src/Shared/DiagnosticDefinitions.cs | 27 +++++++++++++++++++ 14 files changed, 55 insertions(+), 19 deletions(-) rename docs/diagnostics/{OT1000.md => OTEL1000.md} (93%) rename docs/diagnostics/{OT1001.md => OTEL1001.md} (89%) create mode 100644 src/Shared/DiagnosticDefinitions.cs diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index f43ac30b6f6..ac5cf9fafad 100644 --- a/OpenTelemetry.sln +++ b/OpenTelemetry.sln @@ -261,6 +261,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Shared", "Shared", "{A49299 ProjectSection(SolutionItems) = preProject src\Shared\ActivityHelperExtensions.cs = src\Shared\ActivityHelperExtensions.cs src\Shared\ActivityInstrumentationHelper.cs = src\Shared\ActivityInstrumentationHelper.cs + src\Shared\DiagnosticDefinitions.cs = src\Shared\DiagnosticDefinitions.cs src\Shared\ExceptionExtensions.cs = src\Shared\ExceptionExtensions.cs src\Shared\Guard.cs = src\Shared\Guard.cs src\Shared\HttpSemanticConventionHelper.cs = src\Shared\HttpSemanticConventionHelper.cs @@ -317,8 +318,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "getting-started-aspnetcore" EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "diagnostics", "diagnostics", "{52AF6D7D-9E66-4234-9A2C-5D16C6F22B40}" ProjectSection(SolutionItems) = preProject - docs\diagnostics\OT1000.md = docs\diagnostics\OT1000.md - docs\diagnostics\OT1001.md = docs\diagnostics\OT1001.md + docs\diagnostics\OTEL1000.md = docs\diagnostics\OTEL1000.md + docs\diagnostics\OTEL1001.md = docs\diagnostics\OTEL1001.md EndProjectSection EndProject Global diff --git a/build/Common.props b/build/Common.props index 31037f59177..b691de93f9d 100644 --- a/build/Common.props +++ b/build/Common.props @@ -10,7 +10,7 @@ enable enable - $(NoWarn);OT1000;OT1001 + $(NoWarn);OTEL1000;OTEL1001 diff --git a/docs/diagnostics/OT1000.md b/docs/diagnostics/OTEL1000.md similarity index 93% rename from docs/diagnostics/OT1000.md rename to docs/diagnostics/OTEL1000.md index 65041af3441..9291ceabf8f 100644 --- a/docs/diagnostics/OT1000.md +++ b/docs/diagnostics/OTEL1000.md @@ -1,4 +1,4 @@ -# OpenTelemetry .NET Diagnostic: OT1000 +# OpenTelemetry .NET Diagnostic: OTEL1000 ## Overview @@ -38,5 +38,5 @@ usefulness. The OpenTelemetry Specification defines a log bridge API which is rooted off of the `LoggerProvider` (`GetLogger`) and exposes a `Logger` API to submit log -records. See [OT1001](.\OT1001.md) for details about the log bridge +records. See [OTEL1001](.\OTEL1001.md) for details about the log bridge implementation status. diff --git a/docs/diagnostics/OT1001.md b/docs/diagnostics/OTEL1001.md similarity index 89% rename from docs/diagnostics/OT1001.md rename to docs/diagnostics/OTEL1001.md index ae92cd6d548..3e149920b27 100644 --- a/docs/diagnostics/OT1001.md +++ b/docs/diagnostics/OTEL1001.md @@ -1,4 +1,4 @@ -# OpenTelemetry .NET Diagnostic: OT1001 +# OpenTelemetry .NET Diagnostic: OTEL1001 ## Overview @@ -31,4 +31,4 @@ instead of OpenTelemetry directly. ## LoggerProvider API The OpenTelemetry Specification defines a `LoggerProvider` API. See -[OT1000](.\OT1001.md) for details about the log implementation status. +[OTEL1000](.\OTEL1001.md) for details about the log implementation status. diff --git a/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs b/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs index 828b2f4e1ae..c089560696e 100644 --- a/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs +++ b/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs @@ -18,6 +18,7 @@ #if NET8_0_OR_GREATER using System.Diagnostics.CodeAnalysis; +using OpenTelemetry.Internal; #endif namespace OpenTelemetry.Logs; @@ -30,7 +31,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental("OT1000", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +[Experimental(DiagnosticDefinitions.LoggerProviderExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] #endif public #else diff --git a/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs b/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs index f5cf9977dc2..927de0686e3 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs @@ -33,7 +33,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] #endif public #else diff --git a/src/OpenTelemetry.Api/Logs/LogRecordData.cs b/src/OpenTelemetry.Api/Logs/LogRecordData.cs index 6c7ff525b5f..683f24bbc0d 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordData.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordData.cs @@ -19,6 +19,7 @@ using System.Diagnostics; #if NET8_0_OR_GREATER using System.Diagnostics.CodeAnalysis; +using OpenTelemetry.Internal; #endif namespace OpenTelemetry.Logs; @@ -29,7 +30,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] #endif public #else diff --git a/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs b/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs index d552c0f7b0d..d2e571dc0fa 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs @@ -18,6 +18,7 @@ #if NET8_0_OR_GREATER using System.Diagnostics.CodeAnalysis; +using OpenTelemetry.Internal; #endif namespace OpenTelemetry.Logs; @@ -28,7 +29,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] #endif public #else diff --git a/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs b/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs index 13336d5602d..cdd1da22c35 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs @@ -18,6 +18,7 @@ #if NET8_0_OR_GREATER using System.Diagnostics.CodeAnalysis; +using OpenTelemetry.Internal; #endif namespace OpenTelemetry.Logs; @@ -28,7 +29,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] #endif public #else diff --git a/src/OpenTelemetry.Api/Logs/Logger.cs b/src/OpenTelemetry.Api/Logs/Logger.cs index 838105bc400..2f0f15cc56c 100644 --- a/src/OpenTelemetry.Api/Logs/Logger.cs +++ b/src/OpenTelemetry.Api/Logs/Logger.cs @@ -18,6 +18,7 @@ #if NET8_0_OR_GREATER using System.Diagnostics.CodeAnalysis; +using OpenTelemetry.Internal; #endif namespace OpenTelemetry.Logs; @@ -28,7 +29,7 @@ namespace OpenTelemetry.Logs; /// /// WARNING: This is an experimental API which might change or be removed in the future. Use at your own risk. #if NET8_0_OR_GREATER -[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] #endif public #else diff --git a/src/OpenTelemetry.Api/Logs/LoggerProvider.cs b/src/OpenTelemetry.Api/Logs/LoggerProvider.cs index 01dafceb98c..da0b0a989e3 100644 --- a/src/OpenTelemetry.Api/Logs/LoggerProvider.cs +++ b/src/OpenTelemetry.Api/Logs/LoggerProvider.cs @@ -18,6 +18,7 @@ #if NETSTANDARD2_1_OR_GREATER || NET6_0_OR_GREATER using System.Diagnostics.CodeAnalysis; +using OpenTelemetry.Internal; #endif namespace OpenTelemetry.Logs; @@ -28,7 +29,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental("OT1000", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +[Experimental(DiagnosticDefinitions.LoggerProviderExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] #endif public #else @@ -53,7 +54,7 @@ protected LoggerProvider() /// /// instance. #if NET8_0_OR_GREATER - [Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] + [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] #endif public Logger GetLogger() => this.GetLogger(name: null, version: null); @@ -64,7 +65,7 @@ public Logger GetLogger() /// Optional name identifying the instrumentation library. /// instance. #if NET8_0_OR_GREATER - [Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] + [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] #endif public Logger GetLogger(string? name) => this.GetLogger(name, version: null); @@ -76,7 +77,7 @@ public Logger GetLogger(string? name) /// Optional version of the instrumentation library. /// instance. #if NET8_0_OR_GREATER - [Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] + [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] #endif public Logger GetLogger(string? name, string? version) { @@ -97,7 +98,7 @@ public Logger GetLogger(string? name, string? version) /// . /// if the logger was created. #if NET8_0_OR_GREATER - [Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] + [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] #endif protected virtual bool TryCreateLogger( string? name, diff --git a/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs b/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs index 9373fe836a5..5affd2854ba 100644 --- a/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs +++ b/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs @@ -18,6 +18,7 @@ #if NET8_0_OR_GREATER using System.Diagnostics.CodeAnalysis; +using OpenTelemetry.Internal; #endif namespace OpenTelemetry.Logs; @@ -28,7 +29,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental("OT1000", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")] +[Experimental(DiagnosticDefinitions.LoggerProviderExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] #endif public #else diff --git a/src/OpenTelemetry.Api/OpenTelemetry.Api.csproj b/src/OpenTelemetry.Api/OpenTelemetry.Api.csproj index 27aa7389a8d..0a781a94173 100644 --- a/src/OpenTelemetry.Api/OpenTelemetry.Api.csproj +++ b/src/OpenTelemetry.Api/OpenTelemetry.Api.csproj @@ -15,6 +15,7 @@ + diff --git a/src/Shared/DiagnosticDefinitions.cs b/src/Shared/DiagnosticDefinitions.cs new file mode 100644 index 00000000000..1501ba7e881 --- /dev/null +++ b/src/Shared/DiagnosticDefinitions.cs @@ -0,0 +1,27 @@ +// +// Copyright The OpenTelemetry Authors +// +// 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. +// + +#nullable enable + +namespace OpenTelemetry.Internal; + +internal static class DiagnosticDefinitions +{ + public const string UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md"; + + public const string LoggerProviderExperimentalFeature = "OTEL1000"; + public const string LogBridgeApiExperimentalFeature = "OTEL1001"; +} From 1516d1abed72bba951a4d661e8fff949265720b4 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 1 Nov 2023 15:53:10 -0700 Subject: [PATCH 04/13] Warning cleanup. --- src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs | 2 +- src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs | 2 +- src/OpenTelemetry.Api/Logs/LogRecordData.cs | 2 +- src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs | 2 +- src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs | 2 +- src/OpenTelemetry.Api/Logs/Logger.cs | 2 +- src/OpenTelemetry.Api/Logs/LoggerProvider.cs | 2 ++ src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs | 2 +- 8 files changed, 9 insertions(+), 7 deletions(-) diff --git a/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs b/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs index c089560696e..1610a252371 100644 --- a/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs +++ b/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs @@ -16,7 +16,7 @@ #nullable enable -#if NET8_0_OR_GREATER +#if NET8_0_OR_GREATER && EXPOSE_EXPERIMENTAL_FEATURES using System.Diagnostics.CodeAnalysis; using OpenTelemetry.Internal; #endif diff --git a/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs b/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs index 927de0686e3..3bbd773b342 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs @@ -19,7 +19,7 @@ using System.Collections; using System.ComponentModel; using System.Diagnostics; -#if NET8_0_OR_GREATER +#if NET8_0_OR_GREATER && EXPOSE_EXPERIMENTAL_FEATURES using System.Diagnostics.CodeAnalysis; #endif using OpenTelemetry.Internal; diff --git a/src/OpenTelemetry.Api/Logs/LogRecordData.cs b/src/OpenTelemetry.Api/Logs/LogRecordData.cs index 683f24bbc0d..45ebedd3fff 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordData.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordData.cs @@ -17,7 +17,7 @@ #nullable enable using System.Diagnostics; -#if NET8_0_OR_GREATER +#if NET8_0_OR_GREATER && EXPOSE_EXPERIMENTAL_FEATURES using System.Diagnostics.CodeAnalysis; using OpenTelemetry.Internal; #endif diff --git a/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs b/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs index d2e571dc0fa..2a9743a14f9 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs @@ -16,7 +16,7 @@ #nullable enable -#if NET8_0_OR_GREATER +#if NET8_0_OR_GREATER && EXPOSE_EXPERIMENTAL_FEATURES using System.Diagnostics.CodeAnalysis; using OpenTelemetry.Internal; #endif diff --git a/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs b/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs index cdd1da22c35..05784988549 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs @@ -16,7 +16,7 @@ #nullable enable -#if NET8_0_OR_GREATER +#if NET8_0_OR_GREATER && EXPOSE_EXPERIMENTAL_FEATURES using System.Diagnostics.CodeAnalysis; using OpenTelemetry.Internal; #endif diff --git a/src/OpenTelemetry.Api/Logs/Logger.cs b/src/OpenTelemetry.Api/Logs/Logger.cs index 2f0f15cc56c..ea897fc0eeb 100644 --- a/src/OpenTelemetry.Api/Logs/Logger.cs +++ b/src/OpenTelemetry.Api/Logs/Logger.cs @@ -16,7 +16,7 @@ #nullable enable -#if NET8_0_OR_GREATER +#if NET8_0_OR_GREATER && EXPOSE_EXPERIMENTAL_FEATURES using System.Diagnostics.CodeAnalysis; using OpenTelemetry.Internal; #endif diff --git a/src/OpenTelemetry.Api/Logs/LoggerProvider.cs b/src/OpenTelemetry.Api/Logs/LoggerProvider.cs index da0b0a989e3..47a496c1b2e 100644 --- a/src/OpenTelemetry.Api/Logs/LoggerProvider.cs +++ b/src/OpenTelemetry.Api/Logs/LoggerProvider.cs @@ -18,6 +18,8 @@ #if NETSTANDARD2_1_OR_GREATER || NET6_0_OR_GREATER using System.Diagnostics.CodeAnalysis; +#endif +#if NET8_0_OR_GREATER using OpenTelemetry.Internal; #endif diff --git a/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs b/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs index 5affd2854ba..2cb2002880f 100644 --- a/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs +++ b/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs @@ -16,7 +16,7 @@ #nullable enable -#if NET8_0_OR_GREATER +#if NET8_0_OR_GREATER && EXPOSE_EXPERIMENTAL_FEATURES using System.Diagnostics.CodeAnalysis; using OpenTelemetry.Internal; #endif From 2bc3bf2d90dd2ed21c97b50376e1d10f81de9a11 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Mon, 13 Nov 2023 12:36:04 -0800 Subject: [PATCH 05/13] Typo fix. --- docs/diagnostics/OTEL1000.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/diagnostics/OTEL1000.md b/docs/diagnostics/OTEL1000.md index 9291ceabf8f..bfa98ea0e82 100644 --- a/docs/diagnostics/OTEL1000.md +++ b/docs/diagnostics/OTEL1000.md @@ -34,7 +34,7 @@ exposing the same dependency injection surface we have for traces and metrics. We are exposing these APIs to solve these issues and gather feedback about their usefulness. -## Log Bride API +## Log Bridge API The OpenTelemetry Specification defines a log bridge API which is rooted off of the `LoggerProvider` (`GetLogger`) and exposes a `Logger` API to submit log From d1a3bab8d2917d91ef3806c3d0b6ae6100dedfbb Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 16 Nov 2023 20:57:24 -0800 Subject: [PATCH 06/13] Code review. --- OpenTelemetry.sln | 3 +- docs/diagnostics/EXPERIMENTAL_API.md | 40 +++++++++++++++++++ .../Logs/IDeferredLoggerProviderBuilder.cs | 2 +- .../Logs/LogRecordAttributeList.cs | 2 +- src/OpenTelemetry.Api/Logs/LogRecordData.cs | 2 +- .../Logs/LogRecordSeverity.cs | 2 +- .../Logs/LogRecordSeverityExtensions.cs | 2 +- src/OpenTelemetry.Api/Logs/Logger.cs | 2 +- src/OpenTelemetry.Api/Logs/LoggerProvider.cs | 10 ++--- .../Logs/LoggerProviderBuilder.cs | 2 +- src/Shared/DiagnosticDefinitions.cs | 6 +-- 11 files changed, 57 insertions(+), 16 deletions(-) create mode 100644 docs/diagnostics/EXPERIMENTAL_API.md diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index 7e658f568bf..99138142f06 100644 --- a/OpenTelemetry.sln +++ b/OpenTelemetry.sln @@ -269,8 +269,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Shared", "Shared", "{A49299 src\Shared\PeerServiceResolver.cs = src\Shared\PeerServiceResolver.cs src\Shared\PeriodicExportingMetricReaderHelper.cs = src\Shared\PeriodicExportingMetricReaderHelper.cs src\Shared\PooledList.cs = src\Shared\PooledList.cs - src\Shared\ResourceSemanticConventions.cs = src\Shared\ResourceSemanticConventions.cs src\Shared\RequestMethodHelper.cs = src\Shared\RequestMethodHelper.cs + src\Shared\ResourceSemanticConventions.cs = src\Shared\ResourceSemanticConventions.cs src\Shared\SemanticConventions.cs = src\Shared\SemanticConventions.cs src\Shared\SpanAttributeConstants.cs = src\Shared\SpanAttributeConstants.cs src\Shared\SpanHelper.cs = src\Shared\SpanHelper.cs @@ -322,6 +322,7 @@ EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "diagnostics", "diagnostics", "{52AF6D7D-9E66-4234-9A2C-5D16C6F22B40}" ProjectSection(SolutionItems) = preProject docs\diagnostics\OTEL1000.md = docs\diagnostics\OTEL1000.md + docs\diagnostics\EXPERIMENTAL_API.md = docs\diagnostics\EXPERIMENTAL_API.md docs\diagnostics\OTEL1001.md = docs\diagnostics\OTEL1001.md EndProjectSection EndProject diff --git a/docs/diagnostics/EXPERIMENTAL_API.md b/docs/diagnostics/EXPERIMENTAL_API.md new file mode 100644 index 00000000000..9eae3811a32 --- /dev/null +++ b/docs/diagnostics/EXPERIMENTAL_API.md @@ -0,0 +1,40 @@ +# OpenTelemetry .NET Experimental APIs + +This document describes experimental APIs exposed in OpenTelemetry .NET +pre-relase builds. APIs are exposed experimentally when either the OpenTelemetry +Specification has explicitly marked some feature as +[experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md) +or when the SIG members are still working through the design for a feature and +want to solicit feedback from the community. + +> **Note** +> Experimental APIs are exposed as `public` in pre-release builds and `internal` +> in stable builds. + +## Active + +Experimental APIs available in the pre-release builds: + +### OTEL1000 + +Description: `LoggerProvider` and `LoggerProviderBuilder` + +Details: [OTEL1000](./OTEL1000.md) + +### OTEL1001 + +Description: Log Bridge API + +Details: [OTEL1000](./OTEL1001.md) + +## Inactive + +Experimental APIs which have been released stable or removed: + + + +None diff --git a/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs b/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs index 1610a252371..182f501930e 100644 --- a/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs +++ b/src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs @@ -31,7 +31,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental(DiagnosticDefinitions.LoggerProviderExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] +[Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] #endif public #else diff --git a/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs b/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs index 3bbd773b342..0b25c2de44d 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs @@ -33,7 +33,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] +[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] #endif public #else diff --git a/src/OpenTelemetry.Api/Logs/LogRecordData.cs b/src/OpenTelemetry.Api/Logs/LogRecordData.cs index 45ebedd3fff..2e9844b88de 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordData.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordData.cs @@ -30,7 +30,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] +[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] #endif public #else diff --git a/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs b/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs index 2a9743a14f9..c78fcde2502 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs @@ -29,7 +29,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] +[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] #endif public #else diff --git a/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs b/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs index 05784988549..a294eb68148 100644 --- a/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs +++ b/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs @@ -29,7 +29,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] +[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] #endif public #else diff --git a/src/OpenTelemetry.Api/Logs/Logger.cs b/src/OpenTelemetry.Api/Logs/Logger.cs index ea897fc0eeb..e75d84cb68f 100644 --- a/src/OpenTelemetry.Api/Logs/Logger.cs +++ b/src/OpenTelemetry.Api/Logs/Logger.cs @@ -29,7 +29,7 @@ namespace OpenTelemetry.Logs; /// /// WARNING: This is an experimental API which might change or be removed in the future. Use at your own risk. #if NET8_0_OR_GREATER -[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] +[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] #endif public #else diff --git a/src/OpenTelemetry.Api/Logs/LoggerProvider.cs b/src/OpenTelemetry.Api/Logs/LoggerProvider.cs index 47a496c1b2e..7a02b056889 100644 --- a/src/OpenTelemetry.Api/Logs/LoggerProvider.cs +++ b/src/OpenTelemetry.Api/Logs/LoggerProvider.cs @@ -31,7 +31,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental(DiagnosticDefinitions.LoggerProviderExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] +[Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] #endif public #else @@ -56,7 +56,7 @@ protected LoggerProvider() /// /// instance. #if NET8_0_OR_GREATER - [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] + [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] #endif public Logger GetLogger() => this.GetLogger(name: null, version: null); @@ -67,7 +67,7 @@ public Logger GetLogger() /// Optional name identifying the instrumentation library. /// instance. #if NET8_0_OR_GREATER - [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] + [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] #endif public Logger GetLogger(string? name) => this.GetLogger(name, version: null); @@ -79,7 +79,7 @@ public Logger GetLogger(string? name) /// Optional version of the instrumentation library. /// instance. #if NET8_0_OR_GREATER - [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] + [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] #endif public Logger GetLogger(string? name, string? version) { @@ -100,7 +100,7 @@ public Logger GetLogger(string? name, string? version) /// . /// if the logger was created. #if NET8_0_OR_GREATER - [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] + [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] #endif protected virtual bool TryCreateLogger( string? name, diff --git a/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs b/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs index 2cb2002880f..d7fdabeffad 100644 --- a/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs +++ b/src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs @@ -29,7 +29,7 @@ namespace OpenTelemetry.Logs; /// /// #if NET8_0_OR_GREATER -[Experimental(DiagnosticDefinitions.LoggerProviderExperimentalFeature, UrlFormat = DiagnosticDefinitions.UrlFormat)] +[Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] #endif public #else diff --git a/src/Shared/DiagnosticDefinitions.cs b/src/Shared/DiagnosticDefinitions.cs index 1501ba7e881..233cf4b258c 100644 --- a/src/Shared/DiagnosticDefinitions.cs +++ b/src/Shared/DiagnosticDefinitions.cs @@ -20,8 +20,8 @@ namespace OpenTelemetry.Internal; internal static class DiagnosticDefinitions { - public const string UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md"; + public const string ExperimentalApiUrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/EXPERIMENTAL_API.md#{0}"; - public const string LoggerProviderExperimentalFeature = "OTEL1000"; - public const string LogBridgeApiExperimentalFeature = "OTEL1001"; + public const string LoggerProviderExperimentalApi = "OTEL1000"; + public const string LogBridgeApiExperimentalApi = "OTEL1001"; } From 1de32581d948d0b63f7c7633e94efcf660c2ea0f Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 16 Nov 2023 20:58:33 -0800 Subject: [PATCH 07/13] Code review. --- docs/diagnostics/OTEL1000.md | 4 ++-- docs/diagnostics/OTEL1001.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/diagnostics/OTEL1000.md b/docs/diagnostics/OTEL1000.md index bfa98ea0e82..184eb427477 100644 --- a/docs/diagnostics/OTEL1000.md +++ b/docs/diagnostics/OTEL1000.md @@ -2,13 +2,13 @@ ## Overview -This is an experimental feature diagnostic covering the following APIs: +This is an Experimental API diagnostic covering the following APIs: * `LoggerProviderBuilder` * `LoggerProvider` * `IDeferredLoggerProviderBuilder` -Experimental features may be changed or removed in the future. +Experimental APIs may be changed or removed in the future. ## Details diff --git a/docs/diagnostics/OTEL1001.md b/docs/diagnostics/OTEL1001.md index 3e149920b27..a6e15425718 100644 --- a/docs/diagnostics/OTEL1001.md +++ b/docs/diagnostics/OTEL1001.md @@ -2,7 +2,7 @@ ## Overview -This is an experimental feature diagnostic covering the following APIs: +This is an Experimental API diagnostic covering the following APIs: * `LoggerProvider.GetLogger` * `Logger` @@ -10,7 +10,7 @@ This is an experimental feature diagnostic covering the following APIs: * `LogRecordData` * `LogRecordSeverity` -Experimental features may be changed or removed in the future. +Experimental APIs may be changed or removed in the future. ## Details From ac802041af0e8bdd838a2bf24ade505eae2898bc Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 16 Nov 2023 20:59:53 -0800 Subject: [PATCH 08/13] Tweaks. --- docs/diagnostics/OTEL1000.md | 4 ++-- docs/diagnostics/OTEL1001.md | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/diagnostics/OTEL1000.md b/docs/diagnostics/OTEL1000.md index 184eb427477..070714e7841 100644 --- a/docs/diagnostics/OTEL1000.md +++ b/docs/diagnostics/OTEL1000.md @@ -36,7 +36,7 @@ usefulness. ## Log Bridge API -The OpenTelemetry Specification defines a log bridge API which is rooted off of +The OpenTelemetry Specification defines a Log Bridge API which is rooted off of the `LoggerProvider` (`GetLogger`) and exposes a `Logger` API to submit log -records. See [OTEL1001](.\OTEL1001.md) for details about the log bridge +records. See [OTEL1001](.\OTEL1001.md) for details about the Log Bridge API implementation status. diff --git a/docs/diagnostics/OTEL1001.md b/docs/diagnostics/OTEL1001.md index a6e15425718..336d2ebbf60 100644 --- a/docs/diagnostics/OTEL1001.md +++ b/docs/diagnostics/OTEL1001.md @@ -31,4 +31,5 @@ instead of OpenTelemetry directly. ## LoggerProvider API The OpenTelemetry Specification defines a `LoggerProvider` API. See -[OTEL1000](.\OTEL1001.md) for details about the log implementation status. +[OTEL1000](.\OTEL1001.md) for details about the `LoggerProvider` implementation +status. From 5b6281fb4bf4bb8d6f21a3daf239acc0ec30f88e Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 16 Nov 2023 21:02:14 -0800 Subject: [PATCH 09/13] Rename landing doc to be plural. --- OpenTelemetry.sln | 3 +-- docs/diagnostics/{EXPERIMENTAL_API.md => EXPERIMENTAL_APIS.md} | 0 src/Shared/DiagnosticDefinitions.cs | 2 +- 3 files changed, 2 insertions(+), 3 deletions(-) rename docs/diagnostics/{EXPERIMENTAL_API.md => EXPERIMENTAL_APIS.md} (100%) diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index 3ba736b24d2..0519c476984 100644 --- a/OpenTelemetry.sln +++ b/OpenTelemetry.sln @@ -34,7 +34,6 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "build", "build", "{7CB2F02E build\docfx.cmd = build\docfx.cmd build\docker-compose.net6.0.yml = build\docker-compose.net6.0.yml build\docker-compose.net7.0.yml = build\docker-compose.net7.0.yml - build\docker-compose.net8.0.yml = build\docker-compose.net8.0.yml build\finalize-publicapi.ps1 = build\finalize-publicapi.ps1 build\GlobalAttrExclusions.txt = build\GlobalAttrExclusions.txt build\opentelemetry-icon-color.png = build\opentelemetry-icon-color.png @@ -323,7 +322,7 @@ EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "diagnostics", "diagnostics", "{52AF6D7D-9E66-4234-9A2C-5D16C6F22B40}" ProjectSection(SolutionItems) = preProject docs\diagnostics\OTEL1000.md = docs\diagnostics\OTEL1000.md - docs\diagnostics\EXPERIMENTAL_API.md = docs\diagnostics\EXPERIMENTAL_API.md + docs\diagnostics\EXPERIMENTAL_APIS.md = docs\diagnostics\EXPERIMENTAL_APIS.md docs\diagnostics\OTEL1001.md = docs\diagnostics\OTEL1001.md EndProjectSection EndProject diff --git a/docs/diagnostics/EXPERIMENTAL_API.md b/docs/diagnostics/EXPERIMENTAL_APIS.md similarity index 100% rename from docs/diagnostics/EXPERIMENTAL_API.md rename to docs/diagnostics/EXPERIMENTAL_APIS.md diff --git a/src/Shared/DiagnosticDefinitions.cs b/src/Shared/DiagnosticDefinitions.cs index 233cf4b258c..6f8a0ce0b6e 100644 --- a/src/Shared/DiagnosticDefinitions.cs +++ b/src/Shared/DiagnosticDefinitions.cs @@ -20,7 +20,7 @@ namespace OpenTelemetry.Internal; internal static class DiagnosticDefinitions { - public const string ExperimentalApiUrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/EXPERIMENTAL_API.md#{0}"; + public const string ExperimentalApiUrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/EXPERIMENTAL_APIS.md#{0}"; public const string LoggerProviderExperimentalApi = "OTEL1000"; public const string LogBridgeApiExperimentalApi = "OTEL1001"; From 7d908232bdbc09e9c29dc831d4df8c1aba8bd37e Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 16 Nov 2023 21:08:07 -0800 Subject: [PATCH 10/13] Lint. --- docs/diagnostics/EXPERIMENTAL_APIS.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/diagnostics/EXPERIMENTAL_APIS.md b/docs/diagnostics/EXPERIMENTAL_APIS.md index 9eae3811a32..254fb2def67 100644 --- a/docs/diagnostics/EXPERIMENTAL_APIS.md +++ b/docs/diagnostics/EXPERIMENTAL_APIS.md @@ -33,8 +33,10 @@ Experimental APIs which have been released stable or removed: None From f76bba18969a50fd7ff850cd6ba09fe3772389c6 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Fri, 17 Nov 2023 17:31:46 -0800 Subject: [PATCH 11/13] Update docs/diagnostics/EXPERIMENTAL_APIS.md --- docs/diagnostics/EXPERIMENTAL_APIS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/diagnostics/EXPERIMENTAL_APIS.md b/docs/diagnostics/EXPERIMENTAL_APIS.md index 254fb2def67..6333099f527 100644 --- a/docs/diagnostics/EXPERIMENTAL_APIS.md +++ b/docs/diagnostics/EXPERIMENTAL_APIS.md @@ -25,7 +25,7 @@ Details: [OTEL1000](./OTEL1000.md) Description: Log Bridge API -Details: [OTEL1000](./OTEL1001.md) +Details: [OTEL1001](./OTEL1001.md) ## Inactive From 09dec3ac73c5844112f30404cfc5eeb185b071df Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 7 Dec 2023 10:30:06 -0800 Subject: [PATCH 12/13] Copyright header updates. --- src/Shared/DiagnosticDefinitions.cs | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/src/Shared/DiagnosticDefinitions.cs b/src/Shared/DiagnosticDefinitions.cs index 6f8a0ce0b6e..bc027b62ddb 100644 --- a/src/Shared/DiagnosticDefinitions.cs +++ b/src/Shared/DiagnosticDefinitions.cs @@ -1,18 +1,5 @@ -// // Copyright The OpenTelemetry Authors -// -// 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. -// +// SPDX-License-Identifier: Apache-2.0 #nullable enable From 54b5bdc9f1370e7c61962275cb5a00047e2399eb Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 7 Dec 2023 11:07:47 -0800 Subject: [PATCH 13/13] Code review. --- OpenTelemetry.sln | 14 +++++++---- docs/diagnostics/README.md | 23 +++++++++++++++++++ .../{ => experimental-apis}/OTEL1000.md | 2 +- .../{ => experimental-apis}/OTEL1001.md | 2 +- .../README.md} | 0 src/Shared/DiagnosticDefinitions.cs | 2 +- 6 files changed, 36 insertions(+), 7 deletions(-) create mode 100644 docs/diagnostics/README.md rename docs/diagnostics/{ => experimental-apis}/OTEL1000.md (96%) rename docs/diagnostics/{ => experimental-apis}/OTEL1001.md (94%) rename docs/diagnostics/{EXPERIMENTAL_APIS.md => experimental-apis/README.md} (100%) diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index 200311b6082..f4d72580bb3 100644 --- a/OpenTelemetry.sln +++ b/OpenTelemetry.sln @@ -91,8 +91,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "workflows", "workflows", "{ ProjectSection(SolutionItems) = preProject .github\workflows\ci-aot-md.yml = .github\workflows\ci-aot-md.yml .github\workflows\ci-aot.yml = .github\workflows\ci-aot.yml - .github\workflows\ci-concurrency.yml = .github\workflows\ci-concurrency.yml .github\workflows\ci-concurrency-md.yml = .github\workflows\ci-concurrency-md.yml + .github\workflows\ci-concurrency.yml = .github\workflows\ci-concurrency.yml .github\workflows\ci-instrumentation-libraries-md.yml = .github\workflows\ci-instrumentation-libraries-md.yml .github\workflows\ci-instrumentation-libraries.yml = .github\workflows\ci-instrumentation-libraries.yml .github\workflows\ci-md.yml = .github\workflows\ci-md.yml @@ -325,9 +325,14 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "links-creation", "docs\trac EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "diagnostics", "diagnostics", "{52AF6D7D-9E66-4234-9A2C-5D16C6F22B40}" ProjectSection(SolutionItems) = preProject - docs\diagnostics\OTEL1000.md = docs\diagnostics\OTEL1000.md - docs\diagnostics\EXPERIMENTAL_APIS.md = docs\diagnostics\EXPERIMENTAL_APIS.md - docs\diagnostics\OTEL1001.md = docs\diagnostics\OTEL1001.md + docs\diagnostics\README.md = docs\diagnostics\README.md + EndProjectSection +EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "experimental-apis", "experimental-apis", "{17A22B0E-6EC3-4A39-B955-0A486AD06699}" + ProjectSection(SolutionItems) = preProject + docs\diagnostics\experimental-apis\OTEL1000.md = docs\diagnostics\experimental-apis\OTEL1000.md + docs\diagnostics\experimental-apis\OTEL1001.md = docs\diagnostics\experimental-apis\OTEL1001.md + docs\diagnostics\experimental-apis\README.md = docs\diagnostics\experimental-apis\README.md EndProjectSection EndProject Global @@ -658,6 +663,7 @@ Global {99B4D965-8782-4694-8DFA-B7A3630CEF60} = {3862190B-E2C5-418E-AFDC-DB281FB5C705} {B4856711-6D4C-4246-A686-49458D4C1301} = {5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818} {52AF6D7D-9E66-4234-9A2C-5D16C6F22B40} = {7C87CAF9-79D7-4C26-9FFB-F3F1FB6911F1} + {17A22B0E-6EC3-4A39-B955-0A486AD06699} = {52AF6D7D-9E66-4234-9A2C-5D16C6F22B40} EndGlobalSection GlobalSection(ExtensibilityGlobals) = postSolution SolutionGuid = {55639B5C-0770-4A22-AB56-859604650521} diff --git a/docs/diagnostics/README.md b/docs/diagnostics/README.md new file mode 100644 index 00000000000..2c959a6278e --- /dev/null +++ b/docs/diagnostics/README.md @@ -0,0 +1,23 @@ +# OpenTelemetry Diagnostics + +This document describes the diagnostic categories used in OpenTelemetry .NET +components. Diagnostics are used by the compiler to report information to users +about experimental and/or obsolete code being invoked or to suggest improvements +to specific code patterns identified through static analysis. + +## Experimental APIs + +Range: OTEL1XXX + +Experimental APIs exposed in OpenTelemetry .NET pre-relase builds. APIs are +exposed experimentally when either the OpenTelemetry Specification has +explicitly marked some feature as +[experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md) +or when the SIG members are still working through the design for a feature and +want to solicit feedback from the community. + +> **Note** Experimental APIs are exposed as `public` in pre-release builds and +> `internal` in stable builds. + +For defined diagnostics see: [OpenTelemetry .NET Experimental +APIs](./experimental-apis/README.md) diff --git a/docs/diagnostics/OTEL1000.md b/docs/diagnostics/experimental-apis/OTEL1000.md similarity index 96% rename from docs/diagnostics/OTEL1000.md rename to docs/diagnostics/experimental-apis/OTEL1000.md index 070714e7841..5febb4f7ab4 100644 --- a/docs/diagnostics/OTEL1000.md +++ b/docs/diagnostics/experimental-apis/OTEL1000.md @@ -38,5 +38,5 @@ usefulness. The OpenTelemetry Specification defines a Log Bridge API which is rooted off of the `LoggerProvider` (`GetLogger`) and exposes a `Logger` API to submit log -records. See [OTEL1001](.\OTEL1001.md) for details about the Log Bridge API +records. See [OTEL1001](./OTEL1001.md) for details about the Log Bridge API implementation status. diff --git a/docs/diagnostics/OTEL1001.md b/docs/diagnostics/experimental-apis/OTEL1001.md similarity index 94% rename from docs/diagnostics/OTEL1001.md rename to docs/diagnostics/experimental-apis/OTEL1001.md index 336d2ebbf60..66c1f7627ec 100644 --- a/docs/diagnostics/OTEL1001.md +++ b/docs/diagnostics/experimental-apis/OTEL1001.md @@ -31,5 +31,5 @@ instead of OpenTelemetry directly. ## LoggerProvider API The OpenTelemetry Specification defines a `LoggerProvider` API. See -[OTEL1000](.\OTEL1001.md) for details about the `LoggerProvider` implementation +[OTEL1000](./OTEL1000.md) for details about the `LoggerProvider` implementation status. diff --git a/docs/diagnostics/EXPERIMENTAL_APIS.md b/docs/diagnostics/experimental-apis/README.md similarity index 100% rename from docs/diagnostics/EXPERIMENTAL_APIS.md rename to docs/diagnostics/experimental-apis/README.md diff --git a/src/Shared/DiagnosticDefinitions.cs b/src/Shared/DiagnosticDefinitions.cs index bc027b62ddb..7e6fb6af6cf 100644 --- a/src/Shared/DiagnosticDefinitions.cs +++ b/src/Shared/DiagnosticDefinitions.cs @@ -7,7 +7,7 @@ namespace OpenTelemetry.Internal; internal static class DiagnosticDefinitions { - public const string ExperimentalApiUrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/EXPERIMENTAL_APIS.md#{0}"; + public const string ExperimentalApiUrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/experimental-apis/README.md#{0}"; public const string LoggerProviderExperimentalApi = "OTEL1000"; public const string LogBridgeApiExperimentalApi = "OTEL1001";