Skip to content

Commit a36dd78

Browse files
matt-hensleymatt-hensley
authored
Updates installation and configuration documentation for GA release (#119)
1 parent 3b469ad commit a36dd78

13 files changed

+107
-61
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ documents:
7171
* [Installation](./docs/installation.md)
7272
* [Configuration](./docs/configuration.md)
7373
* [Supported instrumentations](./docs/supported-instrumentations.md)
74+
* [Supported resource detectors](./docs/supported-resource-detectors.md)
7475
* [Migrating to upstream](./docs/migration.md)
7576

7677
## Troubleshooting

‎docs/configuration.md

Lines changed: 46 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -168,13 +168,44 @@ using var tracerProvider = Sdk.CreateMeterProviderBuilder()
168168

169169
Alternatively, instrumentation libraries can be disabled by the environment
170170
variable `GRAFANA_DOTNET_DISABLE_INSTRUMENTATIONS`. This variable can be
171-
populated with a comma-separated list of instrumentation library identifiers
172-
from the table above:
171+
populated with a comma-separated list of
172+
[instrumentation library identifiers](./supported-instrumentations.md):
173173

174174
```sh
175175
export GRAFANA_DOTNET_DISABLE_INSTRUMENTATIONS="Process,NetRuntime"
176176
```
177177

178+
### Adding instrumentations not supported by the distribution
179+
180+
Instrumentations not included in the distribution can easily be added by
181+
extension methods on the tracer and meter provider.
182+
183+
For example, if it is desired to use the `EventCounters` instrumentation, which is
184+
not included in the [full package](./installation.md#install-the-full-package-with-all-available-instrumentations),
185+
one install the `EventCounters` instrumentation library along with the base
186+
package.
187+
188+
```sh
189+
dotnet add package --prerelease Grafana.OpenTelemetry.Base
190+
dotnet add package OpenTelemetry.Instrumentation.EventCounters --prerelease
191+
```
192+
193+
Then, the `EventCounters` instrumentation can be enabled via the [`AddEventCountersInstrumentation`](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.EventCounters#step-2-enable-eventcounters-instrumentation)
194+
extension method, alongside the `UseGrafana` method.
195+
196+
```csharp
197+
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
198+
.UseGrafana()
199+
.AddEventCountersInstrumentation(options => {
200+
options.RefreshIntervalSecs = 1;
201+
options.AddEventSources("MyEventSource");
202+
})
203+
.Build();
204+
```
205+
206+
This way, any other instrumentation library [not supported by the distribution](./supported-instrumentations.md)
207+
can be added according to the documentation provided with it.
208+
178209
## Resource detector configuration
179210

180211
### Specifying resource detectors
@@ -193,11 +224,12 @@ using var tracerProvider = Sdk.CreateMeterProviderBuilder()
193224
```
194225

195226
Alternatively, resource detectors can be specified by the environment
196-
variable `GRAFANA_DOTNET_RESOURCEDETECTORS`. This variable can be
197-
populated with a comma-separated list of resource detector identifiers:
227+
variable `GRAFANA_DOTNET_RESOURCE_DETECTORS`. This variable can be
228+
populated with a comma-separated list of
229+
[resource detector identifiers](./supported-resource-detectors.md):
198230

199231
```sh
200-
export GRAFANA_DOTNET_RESOURCEDETECTORS="Process"
232+
export GRAFANA_DOTNET_RESOURCE_DETECTORS="Process"
201233
```
202234

203235
### Disabling resource detectors
@@ -217,42 +249,31 @@ using var tracerProvider = Sdk.CreateMeterProviderBuilder()
217249
```
218250

219251
Alternatively, resource detectors can be disabled by the environment
220-
variable `GRAFANA_DOTNET_DISABLE_RESOURCEDETECTORS`. This variable can be
252+
variable `GRAFANA_DOTNET_DISABLE_RESOURCE_DETECTORS`. This variable can be
221253
populated with a comma-separated list of resource detector identifiers:
222254

223255
```sh
224-
export GRAFANA_DOTNET_DISABLE_RESOURCEDETECTORS="Host,Process"
256+
export GRAFANA_DOTNET_DISABLE_RESOURCE_DETECTORS="Host,Process"
225257
```
226258

227-
### Adding instrumentations not supported by the distribution
259+
### Adding resource detectors not supported by the distribution
228260

229-
Instrumentations not included in the distribution can easily be added by
261+
Resource detectors not included in the distribution can easily be added by
230262
extension methods on the tracer and meter provider.
231263

232-
For example, if it is desired to use the `EventCounters` instrumentation, which is
233-
not included in the [full package](./installation.md#install-the-full-package-with-all-available-instrumentations),
234-
one install the `EventCounters` instrumentation library along with the base
235-
package.
236-
237-
```sh
238-
dotnet add package --prerelease Grafana.OpenTelemetry.Base
239-
dotnet add package OpenTelemetry.Instrumentation.EventCounters --prerelease
240-
```
241-
242-
Then, the `EventCounters` instrumentation can be enabled via the [`AddEventCountersInstrumentation`](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.EventCounters#step-2-enable-eventcounters-instrumentation)
264+
To enable an unsupported resource detector, call the `ConfigureResource`
243265
extension method, alongside the `UseGrafana` method.
244266

245267
```csharp
246268
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
247269
.UseGrafana()
248-
.AddEventCountersInstrumentation(options => {
249-
options.RefreshIntervalSecs = 1;
250-
options.AddEventSources("MyEventSource");
270+
.ConfigureResource(config => {
271+
config.AddCustomResourceDetector();
251272
})
252273
.Build();
253274
```
254275

255-
This way, any other instrumentation library [not supported by the distribution](./supported-instrumentations.md)
276+
This way, any other resource detector library [not supported by the distribution](./supported-resource-detectors.md)
256277
can be added according to the documentation provided with it.
257278

258279
### Extra steps to activate specific instrumentations
@@ -361,4 +382,4 @@ are not contained in the distribution.
361382
| Variable | Example value | Description |
362383
| ----------------------------------------- | ------------------ | ----------- |
363384
| `GRAFANA_DOTNET_DISABLE_INSTRUMENTATIONS` | "Process,NetRuntime" | A comma-separated list of instrumentations to disable. |
364-
| `GRAFANA_DOTNET_DISABLE_RESOURCEDETECTORS`| "Host" | A comma-separated list of resource detectors to disable. |
385+
| `GRAFANA_DOTNET_DISABLE_RESOURCE_DETECTORS`| "Host" | A comma-separated list of resource detectors to disable. |

‎docs/installation.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,9 @@ package to your project.
3939
dotnet add package --prerelease Grafana.OpenTelemetry.Base
4040
```
4141

42-
The list of [supported instrumentations](./supported-instrumentations.md)
43-
specifies what instrumentations are included in the base package.
42+
The list of [supported instrumentations](./supported-instrumentations.md) and
43+
[supported resource detectors](./supported-resource-detectors.md)
44+
specify which are included in the base package and enabled by default.
4445

4546
## Minimizing unneeded dependencies
4647

@@ -52,8 +53,8 @@ dependencies.
5253

5354
To mitigate this situation, [base package](#install-the-base-package)
5455
with a built-in lazy-loading mechanism can be used. This mechanism will
55-
initialize any known available instrumentation library assembly, regardless of
56-
whether it's added as dependency of the [full package](#install-the-full-package-with-all-available-instrumentations)
56+
initialize known available instrumentation library or resource detectors
57+
assembly, regardless of whether it's added as dependency of the [full package](#install-the-full-package-with-all-available-instrumentations)
5758
or as part of the instrumented project.
5859

5960
For example, if it is desired to use the `AspNetCore` instrumentation without
@@ -76,5 +77,6 @@ using var tracerProvider = Sdk.CreateTracerProviderBuilder()
7677
.Build();
7778
```
7879

79-
This way, any other instrumentation library [supported by the distribution](./supported-instrumentations.md)
80-
can be added via lazy loading.
80+
This way, any other [instrumentation library](./supported-instrumentations.md)
81+
or [resource detector](./supported-resource-detectors.md) supported by the
82+
distribution can be added via lazy loading.

‎docs/supported-resource-detectors.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Supported resource detectors
2+
3+
The following resource detectors are recognized:
4+
5+
| Identifier | Enabled by default | Pre-installed | Library name |
6+
| --------------------- | ------------------ | ------------------ | ------------ |
7+
| `AWSEBS` | | | [OpenTelemetry.Resources.AWS](https://www.nuget.org/packages/OpenTelemetry.Resources.AWS) |
8+
| `AWSEC2` | | | [OpenTelemetry.Resources.AWS](https://www.nuget.org/packages/OpenTelemetry.Resources.AWS) |
9+
| `AWSECS` | | | [OpenTelemetry.Resources.AWS](https://www.nuget.org/packages/OpenTelemetry.Resources.AWS) |
10+
| `AWSEKS` | | | [OpenTelemetry.Resources.AWS](https://www.nuget.org/packages/OpenTelemetry.Resources.AWS) |
11+
| `AzureAppService` | | | [OpenTelemetry.Resources.Azure](https://www.nuget.org/packages/OpenTelemetry.Resources.Azure) |
12+
| `AzureVM` | | | [OpenTelemetry.Resources.Azure](https://www.nuget.org/packages/OpenTelemetry.Resources.Azure) |
13+
| `AzureContainerApps` | | | [OpenTelemetry.Resources.Azure](https://www.nuget.org/packages/OpenTelemetry.Resources.Azure) |
14+
| `Container` | | :heavy_check_mark: | [OpenTelemetry.Resources.Container](https://www.nuget.org/packages/OpenTelemetry.Resources.Container) |
15+
| `Host` | :heavy_check_mark: | :heavy_check_mark: | [OpenTelemetry.Resources.Host](https://www.nuget.org/packages/OpenTelemetry.Resources.Host) |
16+
| `OperatingSystem` | | | [OpenTelemetry.Resources.OperatingSystem](https://www.nuget.org/packages/OpenTelemetry.Resources.OperatingSystem) |
17+
| `Process` | :heavy_check_mark: | :heavy_check_mark: | [OpenTelemetry.Resources.Process](https://www.nuget.org/packages/OpenTelemetry.Resources.Process) |
18+
| `ProcessRuntime` | :heavy_check_mark: | :heavy_check_mark: | [OpenTelemetry.Resources.ProcessRuntime](https://www.nuget.org/packages/OpenTelemetry.Resources.ProcessRuntime) |
19+
20+
* The `Container` resource detector is included but needs to be explicitly
21+
activated, as activating it in non-container environments can causes erroneous
22+
attributes. A future release may activate it by default.

‎src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEBSDetectorInitializer.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ namespace Grafana.OpenTelemetry
1010
{
1111
internal class AWSEBSDetectorInitializer : ResourceDetectorInitializer
1212
{
13-
public override ResourceDetector Id { get; } = ResourceDetector.AWSEBSDetector;
13+
public override ResourceDetector Id { get; } = ResourceDetector.AWSEBS;
1414

1515
protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder)
1616
{

‎src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEC2DetectorInitializer.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ namespace Grafana.OpenTelemetry
1010
{
1111
internal class AWSEC2DetectorInitializer : ResourceDetectorInitializer
1212
{
13-
public override ResourceDetector Id { get; } = ResourceDetector.AWSEC2Detector;
13+
public override ResourceDetector Id { get; } = ResourceDetector.AWSEC2;
1414

1515
protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder)
1616
{

‎src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSECSDetectorInitializer.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ namespace Grafana.OpenTelemetry
1010
{
1111
internal class AWSECSDetectorInitializer : ResourceDetectorInitializer
1212
{
13-
public override ResourceDetector Id { get; } = ResourceDetector.AWSECSDetector;
13+
public override ResourceDetector Id { get; } = ResourceDetector.AWSECS;
1414

1515
protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder)
1616
{

‎src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEKSDetectorInitializer.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ namespace Grafana.OpenTelemetry
1010
{
1111
internal class AWSEKSDetectorInitializer : ResourceDetectorInitializer
1212
{
13-
public override ResourceDetector Id { get; } = ResourceDetector.AWSEKSDetector;
13+
public override ResourceDetector Id { get; } = ResourceDetector.AWSEKS;
1414

1515
protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder)
1616
{

‎src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureAppServiceDetectorInitializer.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ namespace Grafana.OpenTelemetry
99
{
1010
internal class AzureAppServiceDetectorInitializer : ResourceDetectorInitializer
1111
{
12-
public override ResourceDetector Id { get; } = ResourceDetector.AzureAppServiceDetector;
12+
public override ResourceDetector Id { get; } = ResourceDetector.AzureAppService;
1313

1414
protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder)
1515
{

‎src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureContainerAppsDetectorInitializer.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ namespace Grafana.OpenTelemetry
99
{
1010
internal class AzureContainerAppsDetectorInitializer : ResourceDetectorInitializer
1111
{
12-
public override ResourceDetector Id { get; } = ResourceDetector.AzureContainerAppsDetector;
12+
public override ResourceDetector Id { get; } = ResourceDetector.AzureContainerApps;
1313

1414
protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder)
1515
{

‎src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureVMDetectorInitializer.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ namespace Grafana.OpenTelemetry
99
{
1010
internal class AzureVMDetectorInitializer : ResourceDetectorInitializer
1111
{
12-
public override ResourceDetector Id { get; } = ResourceDetector.AzureVMDetector;
12+
public override ResourceDetector Id { get; } = ResourceDetector.AzureVM;
1313

1414
protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder)
1515
{

‎src/Grafana.OpenTelemetry.Base/ResourceDetectors/ResourceDetector.cs

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -11,57 +11,57 @@ namespace Grafana.OpenTelemetry
1111
public enum ResourceDetector
1212
{
1313
/// <summary>
14-
/// AWS EBS Resource Detector (OpenTelemetry.ResourceDetectors.AWS)
14+
/// AWS EBS Resource Detector (OpenTelemetry.Resources.AWS)
1515
/// </summary>
16-
AWSEBSDetector,
16+
AWSEBS,
1717
/// <summary>
18-
/// AWS EC2 Resource Detector (OpenTelemetry.ResourceDetectors.AWS)
18+
/// AWS EC2 Resource Detector (OpenTelemetry.Resources.AWS)
1919
/// </summary>
20-
AWSEC2Detector,
20+
AWSEC2,
2121
/// <summary>
22-
/// AWS ECS Resource Detector (OpenTelemetry.ResourceDetectors.AWS)
22+
/// AWS ECS Resource Detector (OpenTelemetry.Resources.AWS)
2323
/// </summary>
24-
AWSECSDetector,
24+
AWSECS,
2525
/// <summary>
26-
/// AWS EKS Resource Detector (OpenTelemetry.ResourceDetectors.AWS)
26+
/// AWS EKS Resource Detector (OpenTelemetry.Resources.AWS)
2727
/// </summary>
28-
AWSEKSDetector,
28+
AWSEKS,
2929

3030
/// <summary>
31-
/// Azure App Service Resource Detector (OpenTelemetry.ResourceDetectors.Azure)
31+
/// Azure App Service Resource Detector (OpenTelemetry.Resources.Azure)
3232
/// </summary>
33-
AzureAppServiceDetector,
33+
AzureAppService,
3434
/// <summary>
35-
/// Azure Virtual Machine Resource Detector (OpenTelemetry.ResourceDetectors.Azure)
35+
/// Azure Virtual Machine Resource Detector (OpenTelemetry.Resources.Azure)
3636
/// </summary>
37-
AzureVMDetector,
37+
AzureVM,
3838
/// <summary>
39-
/// Azure Container Apps Resource Detector (OpenTelemetry.ResourceDetectors.Azure)
39+
/// Azure Container Apps Resource Detector (OpenTelemetry.Resources.Azure)
4040
/// </summary>
41-
AzureContainerAppsDetector,
41+
AzureContainerApps,
4242

4343
/// <summary>
44-
/// Container Resource Detector (OpenTelemetry.ResourceDetectors.Container)
44+
/// Container Resource Detector (OpenTelemetry.Resources.Container)
4545
/// </summary>
4646
Container,
4747

4848
/// <summary>
49-
/// Host Resource Detector (OpenTelemetry.ResourceDetectors.Host)
49+
/// Host Resource Detector (OpenTelemetry.Resources.Host)
5050
/// </summary>
5151
Host,
5252

5353
/// <summary>
54-
/// Operating System Resource Detector (OpenTelemetry.ResourceDetectors.OperatingSystem)
54+
/// Operating System Resource Detector (OpenTelemetry.Resources.OperatingSystem)
5555
/// </summary>
5656
OperatingSystem,
5757

5858
/// <summary>
59-
/// Process Resource Detector (OpenTelemetry.ResourceDetectors.Process)
59+
/// Process Resource Detector (OpenTelemetry.Resources.Process)
6060
/// </summary>
6161
Process,
6262

6363
/// <summary>
64-
/// Process Runtime Resource Detector (OpenTelemetry.ResourceDetectors.ProcessRuntime)
64+
/// Process Runtime Resource Detector (OpenTelemetry.Resources.ProcessRuntime)
6565
/// </summary>
6666
ProcessRuntime
6767
}

‎tests/Grafana.OpenTelemetry.Tests/ResourceDetectorTest.cs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,12 @@ public void EnumMatchesInitializers()
1717
{
1818
var expected = new HashSet<ResourceDetector>((ResourceDetector[])Enum.GetValues(typeof(ResourceDetector)));
1919
#if NETSTANDARD
20-
expected.Remove(ResourceDetector.AWSEBSDetector);
21-
expected.Remove(ResourceDetector.AWSEC2Detector);
20+
expected.Remove(ResourceDetector.AWSEBS);
21+
expected.Remove(ResourceDetector.AWSEC2);
2222
#endif
2323
#if NETSTANDARD || NETFRAMEWORK
24-
expected.Remove(ResourceDetector.AWSECSDetector);
25-
expected.Remove(ResourceDetector.AWSEKSDetector);
24+
expected.Remove(ResourceDetector.AWSECS);
25+
expected.Remove(ResourceDetector.AWSEKS);
2626
#endif
2727
#if !NET6_0_OR_GREATER
2828
expected.Remove(ResourceDetector.Container);

0 commit comments

Comments
 (0)