Skip to content

Commit

Permalink
Update documentation and add documentation to README files
Browse files Browse the repository at this point in the history
  • Loading branch information
ppittle committed Dec 6, 2024
1 parent ec7356a commit da63599
Show file tree
Hide file tree
Showing 4 changed files with 106 additions and 2 deletions.
34 changes: 34 additions & 0 deletions src/OpenTelemetry.Instrumentation.AWS/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,37 @@ public void ConfigureServices(IServiceCollection services)
.AddOtlpExporter());
}
```

## Semantic Conventions

_For an overview on Semantic Conventions, see https://opentelemetry.io/docs/concepts/semantic-conventions/_.

Check failure on line 39 in src/OpenTelemetry.Instrumentation.AWS/README.md

View workflow job for this annotation

GitHub Actions / lint-md / run-markdownlint

Bare URL used

src/OpenTelemetry.Instrumentation.AWS/README.md:39:47 MD034/no-bare-urls Bare URL used [Context: "https://opentelemetry.io/docs/..."] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md034.md

While this library is intended for production use, it relies on several Semantic Conventions that are

Check failure on line 41 in src/OpenTelemetry.Instrumentation.AWS/README.md

View workflow job for this annotation

GitHub Actions / lint-md / run-markdownlint

Line length

src/OpenTelemetry.Instrumentation.AWS/README.md:41:81 MD013/line-length Line length [Expected: 80; Actual: 101] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md013.md
still considered Experimental, meaning they may undergo additional changes before becoming Stable. This can

Check failure on line 42 in src/OpenTelemetry.Instrumentation.AWS/README.md

View workflow job for this annotation

GitHub Actions / lint-md / run-markdownlint

Line length

src/OpenTelemetry.Instrumentation.AWS/README.md:42:81 MD013/line-length Line length [Expected: 80; Actual: 108] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md013.md
impact the aggregation and analysis of telemetry signals in environments with multiple applications or microservices.

Check failure on line 43 in src/OpenTelemetry.Instrumentation.AWS/README.md

View workflow job for this annotation

GitHub Actions / lint-md / run-markdownlint

Line length

src/OpenTelemetry.Instrumentation.AWS/README.md:43:81 MD013/line-length Line length [Expected: 80; Actual: 117] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md013.md
For example, a microservice using an older version of the Semantic Conventions for Http Attributes may emit

Check failure on line 44 in src/OpenTelemetry.Instrumentation.AWS/README.md

View workflow job for this annotation

GitHub Actions / lint-md / run-markdownlint

Line length

src/OpenTelemetry.Instrumentation.AWS/README.md:44:81 MD013/line-length Line length [Expected: 80; Actual: 107] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md013.md
`"http.method"` with a value of GET, while a different microservice, using a new version of Semantic Convention may instead emit the GET as

Check failure on line 45 in src/OpenTelemetry.Instrumentation.AWS/README.md

View workflow job for this annotation

GitHub Actions / lint-md / run-markdownlint

Line length

src/OpenTelemetry.Instrumentation.AWS/README.md:45:81 MD013/line-length Line length [Expected: 80; Actual: 139] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md013.md
`"http.request.method"`.

Future versions the OpenTelemetry.*.AWS libraries will include updates to the Semantic Convention, which may break compatibility with a previous version.

Check failure on line 48 in src/OpenTelemetry.Instrumentation.AWS/README.md

View workflow job for this annotation

GitHub Actions / lint-md / run-markdownlint

Line length

src/OpenTelemetry.Instrumentation.AWS/README.md:48:81 MD013/line-length Line length [Expected: 80; Actual: 153] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md013.md

To opt-out of automatic upgrades, you can pin to a specific version:

```csharp
using OpenTelemetry;
using OpenTelemetry.Contrib.Extensions.AWSXRay.Trace;
using OpenTelemetry.Trace;

public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddOpenTelemetryTracing((builder) => builder
.AddAWSInstrumentation(opt => {
// pin to a specific Semantic Convention version
opt.SemanticConventionVersion = SemanticConventionVersion.v1_10_EXPERIMENTAL;
});
}
```

__NOTE:__ Once a Semantic Convention becomes Stable, OpenTelemetry.*.AWS libraries will remain on that version until the

Check failure on line 68 in src/OpenTelemetry.Instrumentation.AWS/README.md

View workflow job for this annotation

GitHub Actions / lint-md / run-markdownlint

Line length

src/OpenTelemetry.Instrumentation.AWS/README.md:68:81 MD013/line-length Line length [Expected: 80; Actual: 120] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md013.md
next major version bump.
28 changes: 28 additions & 0 deletions src/OpenTelemetry.Instrumentation.AWSLambda/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,34 @@ public class Function
}
```

## Semantic Conventions

_For an overview on Semantic Conventions, see https://opentelemetry.io/docs/concepts/semantic-conventions/_.

Check failure on line 145 in src/OpenTelemetry.Instrumentation.AWSLambda/README.md

View workflow job for this annotation

GitHub Actions / lint-md / run-markdownlint

Bare URL used

src/OpenTelemetry.Instrumentation.AWSLambda/README.md:145:47 MD034/no-bare-urls Bare URL used [Context: "https://opentelemetry.io/docs/..."] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md034.md

While this library is intended for production use, it relies on several Semantic Conventions that are

Check failure on line 147 in src/OpenTelemetry.Instrumentation.AWSLambda/README.md

View workflow job for this annotation

GitHub Actions / lint-md / run-markdownlint

Line length

src/OpenTelemetry.Instrumentation.AWSLambda/README.md:147:81 MD013/line-length Line length [Expected: 80; Actual: 101] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md013.md
still considered Experimental, meaning they may undergo additional changes before becoming Stable. This can
impact the aggregation and analysis of telemetry signals in environments with multiple applications or microservices.
For example, a microservice using an older version of the Semantic Conventions for Http Attributes may emit
`"http.method"` with a value of GET, while a different microservice, using a new version of Semantic Convention may instead emit the GET as
`"http.request.method"`.

Future versions the OpenTelemetry.*.AWS libraries will include updates to the Semantic Convention, which may break compatibility with a previous version.

To opt-out of automatic upgrades, you can pin to a specific version:

```csharp
using (var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddAWSLambdaConfigurations(opt =>
{
// pin to a specific Semantic Convention version
opt.SemanticConventionVersion = SemanticConventionVersion.v1_10_EXPERIMENTAL;
})
.Build()!);
```

__NOTE:__ Once a Semantic Convention becomes Stable, OpenTelemetry.*.AWS libraries will remain on that version until the
next major version bump.

## Reference

* [OpenTelemetry Project](https://opentelemetry.io/)
Expand Down
42 changes: 42 additions & 0 deletions src/OpenTelemetry.Resources.AWS/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,48 @@ log group ids, log stream names, log stream ids.
- **AWSEKSDetector**: cloud provider, cloud platform, cluster name,
container id.

## Semantic Conventions

_For an overview on Semantic Conventions, see https://opentelemetry.io/docs/concepts/semantic-conventions/_.

While this library is intended for production use, it relies on several Semantic Conventions that are
still considered Experimental, meaning they may undergo additional changes before becoming Stable. This can
impact the aggregation and analysis of telemetry signals in environments with multiple applications or microservices.
For example, a microservice using an older version of the Semantic Conventions for Http Attributes may emit
`"http.method"` with a value of GET, while a different microservice, using a new version of Semantic Convention may instead emit the GET as
`"http.request.method"`.

Future versions the OpenTelemetry.*.AWS libraries will include updates to the Semantic Convention, which may break compatibility with a previous version.

To opt-out of automatic upgrades, you can pin to a specific version:

```csharp
using OpenTelemetry;
using OpenTelemetry.Resources;

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.ConfigureResource(resource => resource.AddAWSEC2Detector(
opt => {
// pin to a specific Semantic Convention version
opt.SemanticConventionVersion = SemanticConventionVersion.v1_10_EXPERIMENTAL;
}
))
// other configurations
.Build();

```
using (var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddAWSLambdaConfigurations(opt =>
{
// pin to a specific Semantic Convention version
opt.SemanticConventionVersion = SemanticConventionVersion.v1_10_EXPERIMENTAL;
})
.Build()!);
```
__NOTE:__ Once a Semantic Convention becomes Stable, OpenTelemetry.*.AWS libraries will remain on that version until the
next major version bump.
## References
- [OpenTelemetry Project](https://opentelemetry.io/)
Expand Down
4 changes: 2 additions & 2 deletions src/Shared/AWS/SemanticConventionVersion.cs
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ namespace OpenTelemetry.AWS;
/// still considered Experimental, meaning they may undergo additional changes before becoming Stable. This can
/// impact the aggregation and analysis of telemetry signals in environments with multiple applications or microservices.
/// For example, a microservice using an older version of the Semantic Conventions for Http Attributes may emit
/// <c>"http.method"</c> with a value of GET,while a different microservice, using a new version of Semantic Convention may instead emit the GET as
/// <c>"http.method"</c> with a value of GET, while a different microservice, using a new version of Semantic Convention may instead emit the GET as
/// <c>"http.request.method"</c>.
/// </para>
/// <para>
Expand All @@ -26,7 +26,7 @@ namespace OpenTelemetry.AWS;
/// {
/// opt.SemanticConventionVersion = SemanticConventionVersion.v1_10_EXPERIMENTAL;
/// })
/// .Build()!)
/// .Build()!);
/// ]]>
/// </code>
/// </para>
Expand Down

0 comments on commit da63599

Please sign in to comment.