Skip to content

Commit abbc9e3

Browse files
RichardChukwuRichardChukwu
committed
Automated the Link Transformation process during the build process so that before the NuGet package is published, relative links are converted to absolute links.
did this by updating the .csproj file to include a custom MSBuild task that processes the README.md file, replacing relative links with absolute ones.
1 parent 48c86d9 commit abbc9e3

File tree

3 files changed

+75
-148
lines changed

3 files changed

+75
-148
lines changed

‎src/OpenTelemetry/OpenTelemetry.csproj‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
<TargetFrameworks>$(TargetFrameworksForLibrariesExtended)</TargetFrameworks>
55
<Description>OpenTelemetry .NET SDK</Description>
66
<MinVerTagPrefix>core-</MinVerTagPrefix>
7+
<IsPackable>true</IsPackable> <!-- Enable packaging for this project -->
78
</PropertyGroup>
89

910
<ItemGroup>
@@ -26,10 +27,27 @@
2627
<Compile Include="$(RepoRoot)\src\Shared\ThreadSafeRandom.cs" Link="Includes\ThreadSafeRandom.cs" />
2728
</ItemGroup>
2829

30+
<ItemGroup>
31+
<None Include="README.md" Pack="true" PackagePath="" />
32+
<None Include="RELEASENOTES.md" Pack="true" PackagePath="" />
33+
</ItemGroup>
34+
2935
<PropertyGroup>
30-
<PackageReadmeFile>README.md</PackageReadmeFile>
31-
<PackageReleaseNotes>RELEASENOTES.md</PackageReleaseNotes>
32-
</PropertyGroup>
36+
<PackageReadmeFile>README.md</PackageReadmeFile>
37+
<PackageReleaseNotes>RELEASENOTES.md</PackageReleaseNotes>
38+
</PropertyGroup>
39+
40+
<Target Name="UpdateReadmeLinks" BeforeTargets="Pack">
41+
<ReadLinesFromFile File="README.md">
42+
<Output TaskParameter="Lines" ItemName="ReadmeLines" />
43+
</ReadLinesFromFile>
44+
45+
<Message Importance="high" Text="Updating relative links in README.md" />
3346

47+
<WriteLinesToFile
48+
File="README.md"
49+
Lines="@(ReadmeLines->'%(Identity.Replace('CONTRIBUTING.md','https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/CONTRIBUTING.md'))')"
50+
Overwrite="true" />
51+
</Target>
3452

3553
</Project>

‎src/OpenTelemetry/README.md‎

Lines changed: 1 addition & 145 deletions
Original file line numberDiff line numberDiff line change
@@ -1,145 +1 @@
1-
# OpenTelemetry .NET SDK
2-
3-
[![NuGet](https://img.shields.io/nuget/v/OpenTelemetry.svg)](https://www.nuget.org/packages/OpenTelemetry)
4-
[![NuGet](https://img.shields.io/nuget/dt/OpenTelemetry.svg)](https://www.nuget.org/packages/OpenTelemetry)
5-
6-
<details>
7-
<summary>Table of Contents</summary>
8-
9-
* [Installation](#installation)
10-
* [Introduction](#introduction)
11-
* [Troubleshooting](#troubleshooting)
12-
* [Self-diagnostics](#self-diagnostics)
13-
* [Configuration Parameters](#configuration-parameters)
14-
* [Remarks](#remarks)
15-
* [References](#references)
16-
17-
</details>
18-
19-
## Installation
20-
21-
```shell
22-
dotnet add package OpenTelemetry
23-
```
24-
25-
## Introduction
26-
27-
OpenTelemetry SDK is a reference implementation of the OpenTelemetry API. It
28-
implements the Logging API, Metrics API, Tracing API, Resource API, and the
29-
Context API. Once a valid SDK is installed and configured all the OpenTelemetry
30-
API methods, which were no-ops without an SDK, will start emitting telemetry.
31-
This SDK also ships with
32-
[ILogger](https://learn.microsoft.com/dotnet/core/extensions/logging)
33-
integration to automatically capture and enrich logs emitted using
34-
`Microsoft.Extensions.Logging`.
35-
36-
The SDK deals with concerns such as sampling, processing pipelines (exporting
37-
telemetry to a particular backend, etc.), metrics aggregation, and other
38-
concerns outlined in the [OpenTelemetry
39-
Specification](https://github.com/open-telemetry/opentelemetry-specification).
40-
In most cases, users indirectly install and enable the SDK when they install an
41-
exporter.
42-
43-
To learn how to set up and configure the OpenTelemetry SDK see: [Getting
44-
started](../../README.md#getting-started). For additional details about
45-
initialization patterns see: [Initialize the
46-
SDK](../../docs/README.md#initialize-the-sdk).
47-
48-
## Troubleshooting
49-
50-
All the components shipped from this repo uses
51-
[EventSource](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventsource)
52-
for its internal logging. The name of the `EventSource` used by OpenTelemetry
53-
SDK is "OpenTelemetry-Sdk". To know the `EventSource` names used by other
54-
components, refer to the individual readme files.
55-
56-
While it is possible to view these logs using tools such as
57-
[PerfView](https://github.com/microsoft/perfview),
58-
[dotnet-trace](https://docs.microsoft.com/dotnet/core/diagnostics/dotnet-trace)
59-
etc., this SDK also ships a [self-diagnostics](#self-diagnostics) feature, which
60-
helps with troubleshooting.
61-
62-
### Self-diagnostics
63-
64-
OpenTelemetry SDK ships with built-in self-diagnostics feature. This feature,
65-
when enabled, will listen to internal logs generated by all OpenTelemetry
66-
components (i.e EventSources whose name starts with "OpenTelemetry-") and writes
67-
them to a log file.
68-
69-
The self-diagnostics feature can be enabled/changed/disabled while the process
70-
is running (without restarting the process). The SDK will attempt to read the
71-
configuration file every `10` seconds in non-exclusive read-only mode. The SDK
72-
will create or overwrite a file with new logs according to the configuration.
73-
This file will not exceed the configured max size and will be overwritten in a
74-
circular way.
75-
76-
To enable self-diagnostics, go to the
77-
[current working directory](https://en.wikipedia.org/wiki/Working_directory) of
78-
your process and create a configuration file named `OTEL_DIAGNOSTICS.json` with
79-
the following content:
80-
81-
```json
82-
{
83-
"LogDirectory": ".",
84-
"FileSize": 32768,
85-
"LogLevel": "Warning"
86-
}
87-
```
88-
89-
To disable self-diagnostics, delete the above file.
90-
91-
Tip: In most cases, you could just drop the file along your application.
92-
On Windows, you can use [Process Explorer](https://docs.microsoft.com/sysinternals/downloads/process-explorer),
93-
double click on the process to pop up Properties dialog and find "Current
94-
directory" in "Image" tab.
95-
Internally, it looks for the configuration file located in
96-
[GetCurrentDirectory](https://docs.microsoft.com/dotnet/api/system.io.directory.getcurrentdirectory),
97-
and then [AppContext.BaseDirectory](https://docs.microsoft.com/dotnet/api/system.appcontext.basedirectory).
98-
You can also find the exact directory by calling these methods from your code.
99-
100-
#### Configuration Parameters
101-
102-
1. `LogDirectory` is the directory where the output log file will be stored. It
103-
can be an absolute path or a relative path to the current directory.
104-
105-
2. `FileSize` is a positive integer, which specifies the log file size in
106-
[KiB](https://en.wikipedia.org/wiki/Kibibyte). This value must be within
107-
range `[1024, 131072]` (1 MiB \<= size \<= 128 MiB), or it will be rounded to
108-
the closest upper or lower limit. The log file will never exceed this
109-
configured size, and will be overwritten in a circular way.
110-
111-
3. `LogLevel` is the lowest level of the events to be captured. It has to be one
112-
of the
113-
[values](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventlevel#fields)
114-
of the [`EventLevel`
115-
enum](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventlevel).
116-
The level signifies the severity of an event. Lower severity levels encompass
117-
higher severity levels. For example, `Warning` includes the `Error` and
118-
`Critical` levels.
119-
120-
#### Remarks
121-
122-
A `FileSize`-KiB log file named as `ExecutableName.ProcessId.log` (e.g.
123-
`foobar.exe.12345.log`) will be generated at the specified directory
124-
`LogDirectory`, into which logs are written to.
125-
126-
If the SDK fails to parse the `LogDirectory`, `FileSize` or `LogLevel` fields as
127-
the specified format, the configuration file will be treated as invalid and no
128-
log file would be generated.
129-
130-
When the `LogDirectory` or `FileSize` is found to be changed, the SDK will create
131-
or overwrite a file with new logs according to the new configuration. The
132-
configuration file has to be no more than 4 KiB. In case the file is larger than
133-
4 KiB, only the first 4 KiB of content will be read.
134-
135-
The log file might not be a proper text file format to achieve the goal of having
136-
minimal overhead and bounded resource usage: it may have trailing `NUL`s if log
137-
text is less than configured size; once write operation reaches the end, it will
138-
start from beginning and overwrite existing text.
139-
140-
## References
141-
142-
* [OpenTelemetry Logging SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/sdk.md)
143-
* [OpenTelemetry Metrics SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md)
144-
* [OpenTelemetry Tracing SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md)
145-
* [OpenTelemetry Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md)
1+
@(ReadmeLines->'%(Identity.Replace('CONTRIBUTING.md','https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/CONTRIBUTING.md'))')

‎src/OpenTelemetry/RELEASENOTES.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Release Notes
2+
3+
This file contains highlights and announcements covering all components.
4+
For more details see `CHANGELOG.md` files maintained in the root source
5+
directory of each individual package.
6+
7+
## 1.9.0
8+
9+
* `Exemplars` are now part of the stable API! For details see: [customizing
10+
exemplars
11+
collection](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/metrics/customizing-the-sdk#exemplars).
12+
13+
* `WithLogging` is now part of the stable API! Logging, Metrics, and Tracing can
14+
now all be configured using the `With` style and the builders finally have
15+
parity in their APIs.
16+
17+
## 1.8.0
18+
19+
* `TracerProvider` sampler can now be configured via the `OTEL_TRACES_SAMPLER` &
20+
`OTEL_TRACES_SAMPLER_ARG` envvars.
21+
22+
* A new `UseOtlpExporter` cross-cutting extension has been added to register the
23+
`OtlpExporter` and enable all signals in a single call.
24+
25+
* `exception.type`, `exception.message`, `exception.stacktrace` will now
26+
automatically be included by the `OtlpLogExporter` when logging exceptions.
27+
Previously an experimental environment variable had to be set.
28+
29+
## 1.7.0
30+
31+
* Bumped the package versions of System.Diagnostic.DiagnosticSource and other
32+
Microsoft.Extensions.* packages to `8.0.0`.
33+
34+
* Added `net8.0` targets to all the components.
35+
36+
* OTLP Exporter
37+
* Updated to use `ILogger` `CategoryName` as the instrumentation scope for
38+
logs.
39+
* Added named options support for OTLP Log Exporter.
40+
* Added support for instrumentation scope attributes in metrics.
41+
* Added support under an experimental flag to emit log exception attributes.
42+
* Added support under an experimental flag to emit log eventId and eventName.
43+
attributes.
44+
45+
* Added support for the
46+
[IMetricsBuilder](https://learn.microsoft.com/dotnet/api/microsoft.extensions.diagnostics.metrics.imetricsbuilder)
47+
API.
48+
49+
* Added an experimental opt-in metrics feature to reclaim unused MetricPoints
50+
which enables a higher number of unique dimension combinations to be emitted.
51+
See [reclaim unused metric
52+
points](https://github.com/open-telemetry/opentelemetry-dotnet/blob/32c64d04defb5c92d056fd8817638151168b10da/docs/metrics/README.md#cardinality-limits)
53+
for more details.

0 commit comments

Comments
 (0)