Skip to content

Commit 6e6d490

Browse files
jvoravongjvoravong
authored
Add .NET auto-instrumentations example documentation (#1117)
1 parent 817ac67 commit 6e6d490

File tree

2 files changed

+172
-0
lines changed

2 files changed

+172
-0
lines changed

‎examples/enable-operator-and-auto-instrumentation/auto-instrumentation-dotnet-apm-result.png

104 KB
Loading

‎examples/enable-operator-and-auto-instrumentation/otel-demo-dotnet.md

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Example of chart configuration
2+
3+
## How to deploy the OpenTelemetry Operator and .NET auto-instrumentation
4+
5+
In the following example we will show how to instrument a project using
6+
[dotnet-demo](https://raw.githubusercontent.com/signalfx/splunk-otel-collector-chart/main/functional_tests/testdata/dotnet/deployment.yaml).
7+
8+
### 1. Setup the .NET to instrument
9+
10+
The .NET demo will create a dotnet-demo namespace and deploys the related .NET application to it.
11+
If you have your own .NET application you want to instrument, you can still use the steps below as an example for how
12+
to instrument your application.
13+
14+
```bash
15+
kubectl create namespace dotnet-demo
16+
```
17+
18+
```bash
19+
curl https://raw.githubusercontent.com/signalfx/splunk-otel-collector-chart/main/functional_tests/testdata/dotnet/deployment.yaml | kubectl apply -n dotnet-demo -f -
20+
```
21+
22+
### 2. Complete the steps outlined in [Getting started with auto-instrumentation](../../docs/auto-instrumentation-install.md#steps-for-setting-up-auto-instrumentation)
23+
24+
#### 2.1 Deploy the Helm Chart with the Operator enabled
25+
26+
To install the chart with operator in an existing cluster, make sure you have cert-manager installed and available.
27+
Both the cert-manager and operator are subcharts of this chart and can be enabled with `--set certmanager.enabled=true,operator.enabled=true`.
28+
These helm install commands will deploy the chart to the current namespace for this example.
29+
30+
```bash
31+
# Check if a cert-manager is already installed by looking for cert-manager pods.
32+
kubectl get pods -l app=cert-manager --all-namespaces
33+
34+
# If cert-manager is deployed, make sure to remove certmanager.enabled=true to the list of values to set
35+
helm install splunk-otel-collector -f ./my_values.yaml --set operator.enabled=true,certmanager.enabled=true,environment=dev splunk-otel-collector-chart/splunk-otel-collector
36+
```
37+
38+
#### 2.2 Verify all the OpenTelemetry resources (collector, operator, webhook, instrumentation) are deployed successfully
39+
40+
<details>
41+
<summary>Expand for kubectl commands to run and output</summary>
42+
43+
```bash
44+
kubectl get pods
45+
# NAME READY STATUS RESTARTS AGE
46+
# splunk-otel-collector-agent-2mtfn 2/2 Running 0 5m
47+
# splunk-otel-collector-agent-k4gc8 2/2 Running 0 5m
48+
# splunk-otel-collector-agent-wjt98 2/2 Running 0 5m
49+
# splunk-otel-collector-certmanager-69b98cc84d-2vzl7 1/1 Running 0 5m
50+
# splunk-otel-collector-certmanager-cainjector-76db6dcbbf-4625c 1/1 Running 0 5m
51+
# splunk-otel-collector-certmanager-webhook-bc68cd487-dctrf 1/1 Running 0 5m
52+
# splunk-otel-collector-k8s-cluster-receiver-8449bfdc8-hhbvz 1/1 Running 0 5m
53+
# splunk-otel-collector-operator-754c9d78f8-9ztwg 2/2 Running 0 5m
54+
55+
kubectl get mutatingwebhookconfiguration.admissionregistration.k8s.io
56+
# NAME WEBHOOKS AGE
57+
# splunk-otel-collector-certmanager-webhook 1 8m
58+
# splunk-otel-collector-operator-mutation 3 2m
59+
60+
kubectl get otelinst
61+
# NAME AGE ENDPOINT
62+
# splunk-otel-collector 5m http://$(SPLUNK_OTEL_AGENT):4317
63+
64+
kubectl get pods -n dotnet-demo
65+
# NAME READY STATUS RESTARTS AGE
66+
# dotnet-test-66798c94cc-qmmzv 1/1 Running 0 2m11s
67+
```
68+
69+
</details>
70+
71+
#### 2.3 Instrument Application by Setting Annotations
72+
73+
When instrumenting your .NET application, specific annotations must be set to correctly of your application.
74+
This section covers how to instrument a .NET deployment, specifically `dotnet-test`, which is a `linux-x64` runtime environment.
75+
76+
.NET auto-instrumentation uses annotations to set the [.NET Runtime Identifiers (RIDs)](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog). There are currently two supported RIDs:
77+
78+
1. **linux-x64**:
79+
This is the default value and is typically used for most Linux distributions. It can be omitted since it is assumed by default.
80+
- Annotation: `instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: "linux-x64"`
81+
82+
2. **linux-musl-x64**:
83+
This should be used specifically for applications running in environments based on the musl library.
84+
- Annotation: `instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: "linux-musl-x64"`
85+
86+
**Applying the Auto-Instrumentation Annotations:**
87+
88+
The `dotnet-test` app deployed by the `dotnet-test` deployment is a glibc-based application and uses the linux-x64 runtime environment. Therefore, it is appropriate to apply the following annotation.
89+
90+
- Example command:
91+
```bash
92+
kubectl patch deployment dotnet-test -n dotnet-demo -p '{"spec": {"template":{"metadata":{"annotations":{"instrumentation.opentelemetry.io/otel-dotnet-auto-runtime":"linux-x64"}}}} }'
93+
```
94+
95+
Once the runtime environment is specified, the next step is to apply the auto-instrumentation annotation. This enables OpenTelemetry to automatically instrument your application.
96+
97+
- For `dotnet-test`, use this command:
98+
```bash
99+
kubectl patch deployment dotnet-test -n dotnet-demo -p '{"spec": {"template":{"metadata":{"annotations":{"instrumentation.opentelemetry.io/inject-dotnet":"default/splunk-otel-collector"}}}} }'
100+
```
101+
102+
**Note:**
103+
- This will cause the dotnet-test pod to restart.
104+
- The annotation value "default/splunk-otel-collector" refers to the Instrumentation configuration named `splunk-otel-collector` in the `default` namespace.
105+
- If the chart is not installed in the "default" namespace, modify the annotation value to be "{chart_namespace}/splunk-otel-collector".
106+
- For troubleshooting purposes, examining the logs located in /var/log/opentelemetry/dotnet within the instrumented pod can provide valuable debugging insights.
107+
108+
Remove the annotations to disable instrumentation:
109+
110+
```bash
111+
kubectl patch deployment dotnet-test -n dotnet-demo --type=json -p='[{"op": "remove", "path": "/spec/template/metadata/annotations/instrumentation.opentelemetry.io~1otel-dotnet-auto-runtime"}]'
112+
kubectl patch deployment dotnet-test -n dotnet-demo --type=json -p='[{"op": "remove", "path": "/spec/template/metadata/annotations/instrumentation.opentelemetry.io~1inject-dotnet"}]'
113+
```
114+
115+
You can verify instrumentation was successful on an individual pod with. Check that these bullet points are
116+
true for the instrumented pod using the command below.
117+
- Your instrumented pods should contain an initContainer named `opentelemetry-auto-instrumentation`
118+
- The target application container should have several OTEL_* env variables set that are similar to the output below.
119+
120+
<details>
121+
<summary>Expand for commands to run to verify instrumentation</summary>
122+
123+
```bash
124+
kubectl describe pod -n dotnet-demo -l app=dotnet-test
125+
# Name: dotnet-test-8499bc67dc-wn2fm
126+
# Namespace: dotnet-demo
127+
# Labels: app=dotnet-test
128+
# pod-template-hash=8499bc67dc
129+
# Annotations: instrumentation.opentelemetry.io/inject-dotnet: true
130+
# instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: linux-x64
131+
# Status: Running
132+
# Init Containers:
133+
# opentelemetry-auto-instrumentation-dotnet:
134+
# Image: ghcr.io/signalfx/splunk-otel-dotnet/splunk-otel-dotnet:v1.3.0
135+
# State: Terminated
136+
# Reason: Completed
137+
# Exit Code: 0
138+
# Containers:
139+
# dotnet-test:
140+
# State: Running
141+
# Ready: True
142+
# Environment:
143+
# OTEL_DOTNET_AUTO_PLUGINS: Splunk.OpenTelemetry.AutoInstrumentation.Plugin, Splunk.OpenTelemetry.AutoInstrumentation
144+
# OTEL_EXPORTER_OTLP_ENDPOINT: http://splunk-otel-collector-agent:4318
145+
# CORECLR_ENABLE_PROFILING: 1
146+
# CORECLR_PROFILER: {918728DD-259F-4A6A-AC2B-B85E1B658318}
147+
# CORECLR_PROFILER_PATH: /otel-auto-instrumentation-dotnet/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
148+
# DOTNET_STARTUP_HOOKS: /otel-auto-instrumentation-dotnet/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
149+
# DOTNET_ADDITIONAL_DEPS: /otel-auto-instrumentation-dotnet/AdditionalDeps
150+
# OTEL_DOTNET_AUTO_HOME: /otel-auto-instrumentation-dotnet
151+
# DOTNET_SHARED_STORE: /otel-auto-instrumentation-dotnet/store
152+
# SPLUNK_OTEL_AGENT: (v1:status.hostIP)
153+
# OTEL_SERVICE_NAME: dotnet-test
154+
# OTEL_RESOURCE_ATTRIBUTES_POD_NAME: dotnet-test-8499bc67dc-wkf98 (v1:metadata.name)
155+
# OTEL_RESOURCE_ATTRIBUTES_NODE_NAME: (v1:spec.nodeName)
156+
# OTEL_PROPAGATORS: tracecontext,baggage,b3
157+
# OTEL_RESOURCE_ATTRIBUTES: splunk.zc.method=splunk-otel-dotnet:v1.3.0,k8s.container.name=dotnet-test,k8s.deployment.name=dotnet-test,k8s.namespace.name=dotnet-demo,k8s.node.name=$(OTEL_RESOURCE_ATTRIBUTES_NODE_NAME),k8s.pod.name=$(OTEL_RESOURCE_ATTRIBUTES_POD_NAME),k8s.replicaset.name=dotnet-test-8499bc67dc,service.version=latest
158+
# Mounts:
159+
# /otel-auto-instrumentation-dotnet from opentelemetry-auto-instrumentation-dotnet (rw)
160+
# /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-j5wm6 (ro)
161+
# Volumes:
162+
# opentelemetry-auto-instrumentation-dotnet:
163+
# Type: EmptyDir (a temporary directory that shares a pod's lifetime)
164+
# Medium:
165+
# SizeLimit: 200Mi
166+
```
167+
168+
</details>
169+
170+
#### 2.4 Check out the results at [Splunk Observability APM](https://app.us1.signalfx.com/#/apm)
171+
172+
![APM](auto-instrumentation-dotnet-apm-result.png)

0 commit comments

Comments
 (0)