Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 04a9533

Browse files
mauriciovasquezbernalcodebotenocelotl
authored
docs: Reorganize examples and improve ext packages documentation (open-telemetry#483)
This commit moves the text on the readmes of the external packages to their source code as a docstring. This improves the generated documentation and helps to consolidate the documentation in a single place. Also unify the readmes present on each package to include a 1 line description, installation instructions and a link to the online documentation. This small readme will be the one shown on Github and on PyPI. Also change the examples structure to have the following examples: - basic meter & tracer - http integration - jaeger, prometheus, otcollector{tracer, metrics} - opentracing shim Co-authored-by: alrex <[email protected]> Co-authored-by: Diego Hurtado <[email protected]>
1 parent fbfafa4 commit 04a9533

File tree

62 files changed

+945
-680
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+945
-680
lines changed

‎docs-requirements.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ flask~=1.0
1111
mysql-connector-python ~= 8.0
1212
wrapt >= 1.0.0, < 2.0.0
1313
psycopg2-binary >= 2.7.3.1
14+
prometheus_client >= 0.5.0, < 1.0.0

‎docs/examples/basic_meter/README.rst

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
Basic Meter
2+
===========
3+
4+
These examples show how to use OpenTelemetry to capture and report metrics.
5+
6+
There are three different examples:
7+
8+
* basic_metrics: Shows to how create a metric instrument, how to configure an
9+
exporter and a controller and also how to capture data by using the direct
10+
calling convention.
11+
12+
* calling_conventions: Shows how to use the direct, bound and batch calling conventions.
13+
14+
* observer: Shows how to use the observer instrument.
15+
16+
The source files of these examples are available :scm_web:`here <docs/examples/metrics/>`.
17+
18+
Installation
19+
------------
20+
21+
.. code-block:: sh
22+
23+
pip install opentelemetry-api
24+
pip install opentelemetry-sdk
25+
pip install psutil # needed to get ram and cpu usage in the observer example
26+
27+
Run the Example
28+
---------------
29+
30+
.. code-block:: sh
31+
32+
python <example_name>.py
33+
34+
The output will be shown in the console after few seconds.
35+
36+
Useful links
37+
------------
38+
39+
- OpenTelemetry_
40+
- :doc:`../../api/metrics`
41+
42+
.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/

‎docs/examples/metrics/simple_example.py renamed to ‎docs/examples/basic_meter/basic_metrics.py

Lines changed: 12 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@
1313
# limitations under the License.
1414
#
1515
"""
16-
This module serves as an example for a simple application using metrics
16+
This module serves as an example for a simple application using metrics.
17+
1718
It shows:
1819
- How to configure a meter passing a sateful or stateless.
1920
- How to configure an exporter and how to create a controller.
@@ -27,7 +28,7 @@
2728
from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
2829
from opentelemetry.sdk.metrics.export.controller import PushController
2930

30-
batcher_mode = "stateful"
31+
stateful = True
3132

3233

3334
def usage(argv):
@@ -42,6 +43,11 @@ def usage(argv):
4243
print("bad mode specified.")
4344
usage(sys.argv)
4445
sys.exit(1)
46+
stateful = batcher_mode == "stateful"
47+
48+
print(
49+
"Starting example, values will be printed to the console every 5 seconds."
50+
)
4551

4652

4753
# The Meter is responsible for creating and recording metrics. Each meter has a
@@ -57,7 +63,7 @@ def usage(argv):
5763

5864
# A PushController collects metrics created from meter and exports it via the
5965
# exporter every interval
60-
controller = PushController(meter, exporter, 5)
66+
controller = PushController(meter=meter, exporter=exporter, interval=5)
6167

6268
# Metric instruments allow to capture measurements
6369
requests_counter = meter.create_metric(
@@ -69,15 +75,6 @@ def usage(argv):
6975
label_keys=("environment",),
7076
)
7177

72-
clicks_counter = meter.create_metric(
73-
name="clicks",
74-
description="number of clicks",
75-
unit="1",
76-
value_type=int,
77-
metric_type=Counter,
78-
label_keys=("environment",),
79-
)
80-
8178
requests_size = meter.create_metric(
8279
name="requests_size",
8380
description="size of requests",
@@ -94,17 +91,14 @@ def usage(argv):
9491
testing_label_set = meter.get_label_set({"environment": "testing"})
9592

9693
# Update the metric instruments using the direct calling convention
97-
requests_size.record(100, staging_label_set)
9894
requests_counter.add(25, staging_label_set)
95+
requests_size.record(100, staging_label_set)
9996
time.sleep(5)
10097

101-
requests_size.record(5000, staging_label_set)
10298
requests_counter.add(50, staging_label_set)
99+
requests_size.record(5000, staging_label_set)
103100
time.sleep(5)
104101

105-
requests_size.record(2, testing_label_set)
106102
requests_counter.add(35, testing_label_set)
107-
time.sleep(5)
108-
109-
clicks_counter.add(5, staging_label_set)
103+
requests_size.record(2, testing_label_set)
110104
time.sleep(5)

‎docs/examples/metrics/record.py renamed to ‎docs/examples/basic_meter/calling_conventions.py

Lines changed: 26 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -13,28 +13,23 @@
1313
# limitations under the License.
1414
#
1515
"""
16-
This module serves as an example for a simple application using metrics.
17-
It demonstrates the different ways you can record metrics via the meter.
16+
This example shows how to use the different modes to capture metrics.
17+
It shows the usage of the direct, bound and batch calling conventions.
1818
"""
1919
import time
2020

2121
from opentelemetry import metrics
22-
from opentelemetry.sdk.metrics import Counter, MeterProvider
22+
from opentelemetry.sdk.metrics import Counter, Measure, MeterProvider
2323
from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
2424
from opentelemetry.sdk.metrics.export.controller import PushController
2525

2626
# Use the meter type provided by the SDK package
2727
metrics.set_meter_provider(MeterProvider())
28-
# Meter is responsible for creating and recording metrics
2928
meter = metrics.get_meter(__name__)
30-
# exporter to export metrics to the console
3129
exporter = ConsoleMetricsExporter()
32-
# controller collects metrics created from meter and exports it via the
33-
# exporter every interval
3430
controller = PushController(meter=meter, exporter=exporter, interval=5)
3531

36-
# Example to show how to record using the meter
37-
counter = meter.create_metric(
32+
requests_counter = meter.create_metric(
3833
name="requests",
3934
description="number of requests",
4035
unit="1",
@@ -43,7 +38,16 @@
4338
label_keys=("environment",),
4439
)
4540

46-
counter2 = meter.create_metric(
41+
requests_size = meter.create_metric(
42+
name="requests_size",
43+
description="size of requests",
44+
unit="1",
45+
value_type=int,
46+
metric_type=Measure,
47+
label_keys=("environment",),
48+
)
49+
50+
clicks_counter = meter.create_metric(
4751
name="clicks",
4852
description="number of clicks",
4953
unit="1",
@@ -52,36 +56,27 @@
5256
label_keys=("environment",),
5357
)
5458

55-
# Labelsets are used to identify key-values that are associated with a specific
56-
# metric that you want to record. These are useful for pre-aggregation and can
57-
# be used to store custom dimensions pertaining to a metric
58-
59-
# The meter takes a dictionary of key value pairs
6059
label_set = meter.get_label_set({"environment": "staging"})
6160

62-
# Bound instrument usage
61+
print("Updating using direct calling convention...")
62+
# You can record metrics directly using the metric instrument. You pass in a
63+
# labelset that you would like to record for.
64+
requests_counter.add(25, label_set)
65+
time.sleep(5)
6366

67+
print("Updating using a bound instrument...")
6468
# You can record metrics with bound metric instruments. Bound metric
6569
# instruments are created by passing in a labelset. A bound metric instrument
6670
# is essentially metric data that corresponds to a specific set of labels.
6771
# Therefore, getting a bound metric instrument using the same set of labels
6872
# will yield the same bound metric instrument.
69-
bound_counter = counter.bind(label_set)
70-
for i in range(1000):
71-
bound_counter.add(i)
72-
73-
# You can release the bound instrument we you are done
74-
bound_counter.release()
75-
76-
# Direct metric usage
77-
# You can record metrics directly using the metric instrument. You pass in a
78-
# labelset that you would like to record for.
79-
counter.add(25, label_set)
73+
bound_requests_counter = requests_counter.bind(label_set)
74+
bound_requests_counter.add(100)
75+
time.sleep(5)
8076

81-
# Record batch usage
77+
print("Updating using batch calling convention...")
8278
# You can record metrics in a batch by passing in a labelset and a sequence of
8379
# (metric, value) pairs. The value would be recorded for each metric using the
8480
# specified labelset for each.
85-
meter.record_batch(label_set, [(counter, 50), (counter2, 70)])
86-
87-
time.sleep(10)
81+
meter.record_batch(label_set, ((requests_counter, 50), (clicks_counter, 70)))
82+
time.sleep(5)

‎docs/examples/metrics/observer_example.py renamed to ‎docs/examples/basic_meter/observer.py

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,14 +26,9 @@
2626

2727
# Configure a stateful batcher
2828
batcher = UngroupedBatcher(stateful=True)
29-
3029
metrics.set_meter_provider(MeterProvider())
3130
meter = metrics.get_meter(__name__)
32-
33-
# Exporter to export metrics to the console
3431
exporter = ConsoleMetricsExporter()
35-
36-
# Configure a push controller
3732
controller = PushController(meter=meter, exporter=exporter, interval=2)
3833

3934

@@ -69,4 +64,4 @@ def get_ram_usage_callback(observer):
6964
label_keys=(),
7065
)
7166

72-
input("Press a key to finish...\n")
67+
input("Metrics will be printed soon. Press a key to finish...\n")

‎docs/examples/basic_tracer/README.rst

Lines changed: 12 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,25 @@ Basic Tracer
22
============
33

44
This example shows how to use OpenTelemetry to instrument a Python application - e.g. a batch job.
5-
It supports exporting spans either to the console or to Jaeger_.
65

7-
The source files required to run this example are available :scm_web:`here <docs/examples/basic_tracer/>`.
6+
The source files of this example are available :scm_web:`here <docs/examples/basic_tracer/>`.
87

8+
Installation
9+
------------
910

10-
Run the application
11-
-------------------
11+
.. code-block:: sh
1212
13-
Console
14-
*******
13+
pip install opentelemetry-api
14+
pip install opentelemetry-sdk
1515
16-
* Run the sample
16+
Run the Example
17+
---------------
1718

1819
.. code-block:: sh
1920
20-
$ python tracer.py
21+
python tracer.py
2122
22-
The output will be displayed at the console
23+
The output will be displayed in the console:
2324

2425
::
2526

@@ -29,48 +30,10 @@ The output will be displayed at the console
2930
Span(name="foo", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1d5d87441ec2f410, trace_state={}), kind=SpanKind.INTERNAL, parent=None, start_time=2019-11-07T21:26:45.934369Z, end_time=2019-11-07T21:26:45.934580Z)
3031

3132

32-
Jaeger
33-
******
34-
35-
Setup `Jaeger Tracing <https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one>`_.
36-
37-
* Run the sample
38-
39-
.. code-block:: sh
40-
41-
$ pip install opentelemetry-ext-jaeger
42-
$ EXPORTER=jaeger python tracer.py
43-
44-
45-
The traces should be available in the Jaeger UI at `<http://localhost:16686>`_
46-
47-
48-
Collector
49-
*********
50-
51-
* Start Collector
52-
53-
.. code-block:: sh
54-
55-
$ pip install docker-compose
56-
$ cd docker
57-
$ docker-compose up
58-
59-
* Run the sample
60-
61-
.. code-block:: sh
62-
63-
$ pip install opentelemetry-ext-otcollector
64-
$ EXPORTER=collector python tracer.py
65-
66-
67-
Collector is configured to export to Jaeger, follow Jaeger UI instructions to find the traces.
68-
6933
Useful links
7034
------------
7135

72-
- For more information on OpenTelemetry, visit OpenTelemetry_.
73-
- For more information on tracing in Python, visit Jaeger_.
36+
- OpenTelemetry_
37+
- :doc:`../../api/trace`
7438

75-
.. _Jaeger: https://www.jaegertracing.io/
7639
.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/

‎docs/examples/basic_tracer/tracer.py

Lines changed: 4 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -23,35 +23,17 @@
2323
ConsoleSpanExporter,
2424
)
2525

26-
if os.getenv("EXPORTER") == "jaeger":
27-
from opentelemetry.ext.jaeger import JaegerSpanExporter
28-
29-
print("Using JaegerSpanExporter")
30-
exporter = JaegerSpanExporter(
31-
service_name="basic-service",
32-
agent_host_name="localhost",
33-
agent_port=6831,
34-
)
35-
elif os.getenv("EXPORTER") == "collector":
36-
from opentelemetry.ext.otcollector.trace_exporter import (
37-
CollectorSpanExporter,
38-
)
39-
40-
print("Using CollectorSpanExporter")
41-
exporter = CollectorSpanExporter(
42-
service_name="basic-service", endpoint="localhost:55678"
43-
)
44-
else:
45-
print("Using ConsoleSpanExporter")
46-
exporter = ConsoleSpanExporter()
47-
26+
# The preferred tracer implementation must be set, as the opentelemetry-api
27+
# defines the interface with a no-op implementation.
4828
trace.set_tracer_provider(TracerProvider())
29+
4930
# We tell OpenTelemetry who it is that is creating spans. In this case, we have
5031
# no real name (no setup.py), so we make one up. If we had a version, we would
5132
# also specify it here.
5233
tracer = trace.get_tracer(__name__)
5334

5435
# SpanExporter receives the spans and send them to the target location.
36+
exporter = ConsoleSpanExporter()
5537
span_processor = BatchExportSpanProcessor(exporter)
5638
trace.get_tracer_provider().add_span_processor(span_processor)
5739

0 commit comments

Comments
 (0)