Link up tracing concepts in python manual instrumentation docs (#1591)
* Link up tracing concepts in python manual instrumentation docs * whoospie daisy * third time's the charm? * Apply suggestions from code review Co-authored-by: Srikanth Chekuri <srikanth.chekuri92@gmail.com> Co-authored-by: Srikanth Chekuri <srikanth.chekuri92@gmail.com>
This commit is contained in:
parent
1974236f07
commit
addf78e093
|
@ -17,8 +17,8 @@ pip install opentelemetry-sdk
|
||||||
```
|
```
|
||||||
|
|
||||||
To start tracing, you'll need to initialize a
|
To start tracing, you'll need to initialize a
|
||||||
[`TracerProvider`](/docs/reference/specification/trace/api/#tracerprovider) and optionally set
|
[`TracerProvider`](/docs/concepts/signals/traces/#tracer-provider) and
|
||||||
it as the global default.
|
optionally set it as the global default.
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from opentelemetry import trace
|
from opentelemetry import trace
|
||||||
|
@ -40,8 +40,8 @@ tracer = trace.get_tracer(__name__)
|
||||||
```
|
```
|
||||||
|
|
||||||
To start collecting metrics, you'll need to initialize a
|
To start collecting metrics, you'll need to initialize a
|
||||||
[`MeterProvider`](/docs/reference/specification/metrics/api/#meterprovider) and optionally set
|
[`MeterProvider`](/docs/reference/specification/metrics/api/#meterprovider) and
|
||||||
it as the global default.
|
optionally set it as the global default.
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from opentelemetry import metrics
|
from opentelemetry import metrics
|
||||||
|
@ -65,7 +65,8 @@ meter = metrics.get_meter(__name__)
|
||||||
|
|
||||||
### Creating spans
|
### Creating spans
|
||||||
|
|
||||||
To create a span, you'll typically want it to be started as the current span.
|
To create a [span](/docs/concepts/signals/traces/#spans-in-opentelemetry), you'll
|
||||||
|
typically want it to be started as the current span.
|
||||||
|
|
||||||
```python
|
```python
|
||||||
def do_work():
|
def do_work():
|
||||||
|
@ -81,7 +82,9 @@ span. This is usually done to track concurrent or asynchronous operations.
|
||||||
### Creating nested spans
|
### Creating nested spans
|
||||||
|
|
||||||
If you have a distinct sub-operation you'd like to track as a part of another
|
If you have a distinct sub-operation you'd like to track as a part of another
|
||||||
one, you can create spans to represent the relationship:
|
one, you can create
|
||||||
|
[spans](/docs/concepts/signals/traces/#spans-in-opentelemetry) to represent the
|
||||||
|
relationship:
|
||||||
|
|
||||||
```python
|
```python
|
||||||
def do_work():
|
def do_work():
|
||||||
|
@ -102,8 +105,10 @@ nested span under `parent`.
|
||||||
|
|
||||||
### Creating spans with decorators
|
### Creating spans with decorators
|
||||||
|
|
||||||
It's common to have a single span track the execution of an entire function. In
|
It's common to have a single
|
||||||
that scenario, there is a decorator you can use to reduce code:
|
[span](/docs/concepts/signals/traces/#spans-in-opentelemetry) track the execution
|
||||||
|
of an entire function. In that scenario, there is a decorator you can use to
|
||||||
|
reduce code:
|
||||||
|
|
||||||
```python
|
```python
|
||||||
@tracer.start_as_current_span("do_work")
|
@tracer.start_as_current_span("do_work")
|
||||||
|
@ -123,8 +128,9 @@ use a decorator.
|
||||||
|
|
||||||
### Get the current span
|
### Get the current span
|
||||||
|
|
||||||
Sometimes it's helpful to access whatever the current span is at a point in time
|
Sometimes it's helpful to access whatever the current
|
||||||
so that you can enrich it with more information.
|
[span](/docs/concepts/signals/traces/#spans-in-opentelemetry) is at a point in
|
||||||
|
time so that you can enrich it with more information.
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from opentelemetry import trace
|
from opentelemetry import trace
|
||||||
|
@ -135,8 +141,9 @@ current_span = trace.get_current_span()
|
||||||
|
|
||||||
### Add attributes to a span
|
### Add attributes to a span
|
||||||
|
|
||||||
Attributes let you attach key/value pairs to a span so it carries more
|
[Attributes](/docs/concepts/signals/traces/#attributes) let you attach key/value
|
||||||
information about the current operation that it's tracking.
|
pairs to a [span](/docs/concepts/signals/traces/#spans-in-opentelemetry) so it
|
||||||
|
carries more information about the current operation that it's tracking.
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from opentelemetry import trace
|
from opentelemetry import trace
|
||||||
|
@ -150,8 +157,10 @@ current_span.set_attribute("operation.other-stuff", [1, 2, 3])
|
||||||
|
|
||||||
### Adding events
|
### Adding events
|
||||||
|
|
||||||
An event is a human-readable message on a span that represents "something
|
An [event](/docs/concepts/signals/traces/#span-events) is a human-readable
|
||||||
happening" during its lifetime. You can think of it as a primitive log.
|
message on a [span](/docs/concepts/signals/traces/#spans-in-opentelemetry) that
|
||||||
|
represents "something happening" during its lifetime. You can think of it as a
|
||||||
|
primitive log.
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from opentelemetry import trace
|
from opentelemetry import trace
|
||||||
|
@ -167,8 +176,9 @@ current_span.add_event("Did it!")
|
||||||
|
|
||||||
### Adding links
|
### Adding links
|
||||||
|
|
||||||
A span can be created with zero or more span links that causally link it to
|
A [span](/docs/concepts/signals/traces/#spans-in-opentelemetry) can be created
|
||||||
another span. A link needs a span context to be created.
|
with zero or more span [links](/docs/concepts/signals/traces/#span-links) that
|
||||||
|
causally link it to another span. A link needs a span context to be created.
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from opentelemetry import trace
|
from opentelemetry import trace
|
||||||
|
@ -186,10 +196,11 @@ with tracer.start_as_current_span("new-span", links=[link_from_current]) as new_
|
||||||
|
|
||||||
### Set span status
|
### Set span status
|
||||||
|
|
||||||
A status can be set on a span, typically used to specify that a span has not
|
A [status](/docs/concepts/signals/traces/#span-status) can be set on a
|
||||||
completed successfully - `StatusCode.ERROR`. In rare scenarios, you could
|
[span](/docs/concepts/signals/traces/#spans-in-opentelemetry), typically used to
|
||||||
override the Error status with `StatusCode.OK`, but don’t set `StatusCode.OK` on
|
specify that a span has not completed successfully - `StatusCode.ERROR`. In rare
|
||||||
successfully-completed spans.
|
scenarios, you could override the Error status with `StatusCode.OK`, but don’t
|
||||||
|
set `StatusCode.OK` on successfully-completed spans.
|
||||||
|
|
||||||
The status can be set at any time before the span is finished:
|
The status can be set at any time before the span is finished:
|
||||||
|
|
||||||
|
@ -280,13 +291,13 @@ Note that environment variables will override what's configured in code.
|
||||||
|
|
||||||
Instruments are used to make measurements of your application. [Synchronous
|
Instruments are used to make measurements of your application. [Synchronous
|
||||||
instruments](/docs/reference/specification/metrics/api/#synchronous-and-asynchronous-instruments)
|
instruments](/docs/reference/specification/metrics/api/#synchronous-and-asynchronous-instruments)
|
||||||
are used inline with application/business processing logic, like when handling a request or
|
are used inline with application/business processing logic, like when handling a
|
||||||
calling another service.
|
request or calling another service.
|
||||||
|
|
||||||
First, create your instrument. Instruments are generally created once at the module or class
|
First, create your instrument. Instruments are generally created once at the
|
||||||
level and then used inline with business logic. This example uses a
|
module or class level and then used inline with business logic. This example
|
||||||
[Counter](/docs/reference/specification/metrics/api/#counter) instrument to count the number of
|
uses a [Counter](/docs/reference/specification/metrics/api/#counter) instrument
|
||||||
work items completed:
|
to count the number of work items completed:
|
||||||
|
|
||||||
```python
|
```python
|
||||||
work_counter = meter.create_counter(
|
work_counter = meter.create_counter(
|
||||||
|
@ -294,8 +305,9 @@ work_counter = meter.create_counter(
|
||||||
)
|
)
|
||||||
```
|
```
|
||||||
|
|
||||||
Using the Counter's [add operation](/docs/reference/specification/metrics/api/#add), the code
|
Using the Counter's [add
|
||||||
below increments the count by one, using the work item's type as an attribute.
|
operation](/docs/reference/specification/metrics/api/#add), the code below
|
||||||
|
increments the count by one, using the work item's type as an attribute.
|
||||||
|
|
||||||
```python
|
```python
|
||||||
def do_work(work_item):
|
def do_work(work_item):
|
||||||
|
@ -306,16 +318,18 @@ def do_work(work_item):
|
||||||
|
|
||||||
### Creating and using asynchronous instruments
|
### Creating and using asynchronous instruments
|
||||||
|
|
||||||
[Asynchronous instruments](/docs/reference/specification/metrics/api/#synchronous-and-asynchronous-instruments)
|
[Asynchronous
|
||||||
give the user a way to register callback functions, which are invoked on demand to make
|
instruments](/docs/reference/specification/metrics/api/#synchronous-and-asynchronous-instruments)
|
||||||
measurements. This is useful to periodically measure a value that cannot be instrumented
|
give the user a way to register callback functions, which are invoked on demand
|
||||||
directly. Async instruments are created with zero or more callbacks which will be invoked
|
to make measurements. This is useful to periodically measure a value that cannot
|
||||||
during metric collection. Each callback accepts options from the SDK and returns its
|
be instrumented directly. Async instruments are created with zero or more
|
||||||
observations.
|
callbacks which will be invoked during metric collection. Each callback accepts
|
||||||
|
options from the SDK and returns its observations.
|
||||||
|
|
||||||
This example uses an [Asynchronous Gauge](/docs/reference/specification/metrics/api/#asynchronous-gauge)
|
This example uses an [Asynchronous
|
||||||
instrument to report the current config version provided by a configuration server by scraping
|
Gauge](/docs/reference/specification/metrics/api/#asynchronous-gauge) instrument
|
||||||
an HTTP endpoint. First, write a callback to make observations:
|
to report the current config version provided by a configuration server by
|
||||||
|
scraping an HTTP endpoint. First, write a callback to make observations:
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from typing import Iterable
|
from typing import Iterable
|
||||||
|
@ -332,9 +346,9 @@ def scrape_config_versions(options: CallbackOptions) -> Iterable[Observation]:
|
||||||
)
|
)
|
||||||
```
|
```
|
||||||
|
|
||||||
Note that OpenTelemetry will pass options to your callback containing a timeout. Callbacks
|
Note that OpenTelemetry will pass options to your callback containing a timeout.
|
||||||
should respect this timeout to avoid blocking indefinitely. Finally, create the instrument with
|
Callbacks should respect this timeout to avoid blocking indefinitely. Finally,
|
||||||
the callback to register it:
|
create the instrument with the callback to register it:
|
||||||
|
|
||||||
```python
|
```python
|
||||||
meter.create_observable_gauge(
|
meter.create_observable_gauge(
|
||||||
|
@ -348,11 +362,16 @@ meter.create_observable_gauge(
|
||||||
|
|
||||||
- Trace
|
- Trace
|
||||||
- [Trace Concepts](/docs/concepts/signals/traces/)
|
- [Trace Concepts](/docs/concepts/signals/traces/)
|
||||||
- [Trace Specification](/docs/reference/specification/overview/#tracing-signal)
|
- [Trace
|
||||||
- [Python Trace API Documentation](https://opentelemetry-python.readthedocs.io/en/latest/api/trace.html)
|
Specification](/docs/reference/specification/overview/#tracing-signal)
|
||||||
- [Python Trace SDK Documentation](https://opentelemetry-python.readthedocs.io/en/latest/sdk/trace.html)
|
- [Python Trace API
|
||||||
|
Documentation](https://opentelemetry-python.readthedocs.io/en/latest/api/trace.html)
|
||||||
|
- [Python Trace SDK
|
||||||
|
Documentation](https://opentelemetry-python.readthedocs.io/en/latest/sdk/trace.html)
|
||||||
- Metrics
|
- Metrics
|
||||||
- [Metrics Concepts](/docs/concepts/signals/metrics/)
|
- [Metrics Concepts](/docs/concepts/signals/metrics/)
|
||||||
- [Metrics Specification](/docs/reference/specification/metrics/)
|
- [Metrics Specification](/docs/reference/specification/metrics/)
|
||||||
- [Python Metrics API Documentation](https://opentelemetry-python.readthedocs.io/en/latest/api/metrics.html)
|
- [Python Metrics API
|
||||||
- [Python Metrics SDK Documentation](https://opentelemetry-python.readthedocs.io/en/latest/sdk/metrics.html)
|
Documentation](https://opentelemetry-python.readthedocs.io/en/latest/api/metrics.html)
|
||||||
|
- [Python Metrics SDK
|
||||||
|
Documentation](https://opentelemetry-python.readthedocs.io/en/latest/sdk/metrics.html)
|
||||||
|
|
Loading…
Reference in New Issue