You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Update tracing docs and add note to the @distributed_trace decorator that it's not intended for end users (#37478)
* Update tracing docs and add note to the @distributed_trace decorator
* Apply suggestions from code review
Co-authored-by: Paul Van Eck <[email protected]>
* suppress readme checks
---------
Co-authored-by: Paul Van Eck <[email protected]>
client.create_container('my_container') # Call will be traced
13
39
```
14
40
15
-
Now you can use OpenTelemetry for Python as usual with any SDKs that are compatible
16
-
with azure-core tracing. This includes (not exhaustive list), azure-storage-blob, azure-keyvault-secrets, azure-eventhub, etc.
41
+
The Azure Monitor OpenTelemetry Distro can be found in the [`azure-monitor-opentelemetry`](https://pypi.org/project/azure-monitor-opentelemetry) package.
17
42
18
-
## Key concepts
43
+
## Tracing with generic OpenTelemetry
19
44
20
-
* You don't need to pass any context, SDK will get it for you
21
-
* There are two ways to enable the tracing plugin in code:
45
+
Check out your observability provider documentation on how to enable distributed tracing with OpenTelemetry
46
+
or follow [OpenTelemetry Python documentation](https://opentelemetry.io/docs/languages/python/) on generic configuration.
22
47
23
-
```python
24
-
from azure.core.settings import settings
25
-
from azure.core.tracing.ext.opentelemetry_span import OpenTelemetrySpan
In addition to common OpenTelemetry configuration, follow this steps to configure Azure SDKs:
28
49
29
-
or
50
+
1. Install the Azure Core OpenTelemetry Tracing plugin for Python with [pip](https://pypi.org/project/pip/):
30
51
31
-
```python
32
-
from azure.core.settings import settings
33
-
settings.tracing_implementation ="opentelemetry"
34
-
```
52
+
```bash
53
+
pip install azure-core-tracing-opentelemetry
54
+
```
35
55
36
-
* Alternatively, if you have the latest version of `azure-core` installed, you can also set the following environment variable to enable tracing with OpenTelemetry:
56
+
Now you can use Azure Core OpenTelemetry Tracing plugin for Python as usual with any SDKs that are compatible
57
+
with azure-core tracing. This includes (not exhaustive list), `azure-storage-blob`, `azure-keyvault-secrets`, `azure-eventhub`, etc.
37
58
38
-
```bash
39
-
AZURE_SDK_TRACING_IMPLEMENTATION=opentelemetry
40
-
```
59
+
2. Specify which tracing implementation Azure SDK should use in one of the following ways:
60
+
- By setting `AZURE_SDK_TRACING_IMPLEMENTATION` environment variable to `opentelemetry`
61
+
(just make sure you use a fresh version of `azure-core` and `azure-core-tracing-opentelemetry`)
41
62
42
-
## Examples
63
+
```bash
64
+
AZURE_SDK_TRACING_IMPLEMENTATION=opentelemetry
65
+
```
43
66
44
-
There is no explicit context to pass, you just create your usual opentelemetry tracer and
45
-
call any SDK code that is compatible with azure-core tracing. This is an example
46
-
using Azure Monitor exporter, but you can use any exporter (Zipkin, etc.).
67
+
- Alternatively, you can set it up in the code:
68
+
69
+
```python
70
+
from azure.core.settings import settings
71
+
settings.tracing_implementation = "opentelemetry"
72
+
```
73
+
74
+
This configuration instructs Azure SDK clients to emit spans using global OpenTelemetry instance and
75
+
corresponding tracer provider.
76
+
77
+
There is no need to write any additional code to trace Azure SDK calls or pass trace context explicitly -
78
+
Azure SDKs and OpenTelemetry will do it for you.
79
+
80
+
Here's a full example:
47
81
48
82
```python
49
83
@@ -52,16 +86,10 @@ from azure.core.settings import settings
52
86
53
87
settings.tracing_implementation = "opentelemetry"
54
88
55
-
# In the below example, we use a simple console exporter, uncomment these lines to use
56
-
# the OpenTelemetry exporter for Azure Monitor.
57
-
# Example of a trace exporter for Azure Monitor, but you can use anything OpenTelemetry supports
58
-
# from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
59
-
# exporter = AzureMonitorTraceExporter(
60
-
# connection_string="the connection string used for your Application Insights resource"
61
-
# )
89
+
# In the below example, we use a simple console exporter.
90
+
91
+
# See https://opentelemetry.io/docs/languages/python/ for more details on OpenTelemetry configuration
62
92
63
-
# Regular open telemetry usage from here, see https://github.com/open-telemetry/opentelemetry-python
64
-
# for details
65
93
from opentelemetry import trace
66
94
from opentelemetry.sdk.trace import TracerProvider
67
95
from opentelemetry.sdk.trace.export import ConsoleSpanExporter
@@ -71,7 +99,6 @@ from opentelemetry.sdk.trace.export import SimpleSpanProcessor
client.create_container('my_container') # Call will be traced
86
114
```
87
115
88
-
The Azure Monitor OpenTelemetry Exporter can be found in the [`azure-monitor-opentelemetry-exporter`](https://pypi.org/project/azure-monitor-opentelemetry-exporter/) package.
89
-
90
-
91
116
## HTTP instrumentation
92
117
93
118
With the Azure Core OpenTelemetry Tracing plugin enabled, HTTP requests made by Azure SDK clients are typically instrumented via the [`DistributedTracingPolicy`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/azure/core/pipeline/policies/_distributed_tracing.py) automatically. Since Azure Core handles HTTP instrumentation for Azure service calls, automatic HTTP instrumentation from other libraries such as `opentelemetry-requests-instrumentation` are suppressed to avoid duplicate spans from being created.
94
119
95
-
96
120
## Troubleshooting
97
121
98
122
This client raises exceptions defined in [Azure Core](https://learn.microsoft.com/python/api/azure-core/azure.core.exceptions?view=azure-python).
99
123
100
-
101
-
## Next steps
102
-
103
-
More documentation on OpenTelemetry configuration can be found on the [OpenTelemetry website](https://opentelemetry.io)
104
-
105
-
106
124
## Contributing
107
125
108
126
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
0 commit comments