Skip to content

Commit 6cf2236

Browse files
author
Azfaar Qureshi
committed
updating readme
1 parent 2d5e7c6 commit 6cf2236

File tree

2 files changed

+91
-14
lines changed

2 files changed

+91
-14
lines changed

Diff for: ‎.flake8

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ ignore =
44
F401 # unused import, defer to pylint
55
W503 # allow line breaks before binary ops
66
W504 # allow line breaks after binary ops
7-
E203 # allow whitespace before ':' (https://github.com/psf/black#slices)
7+
E203 # allow whitespace before ':' (https://github.com/psf/black#slices)
88
exclude =
99
.bzr
1010
.git

Diff for: ‎exporter/opentelemetry-exporter-prometheus-remote-write/README.rst

+90-13
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,6 @@ then converts the data into `timeseries`_ and sends it to the Remote
2222
Write integrated backend through HTTP POST requests. The metrics
2323
collection datapath is shown below:
2424

25-
|controller_datapath_final|
2625

2726
See the ``examples`` folder for a demo usage of this exporter
2827

@@ -34,6 +33,7 @@ Table of Contents
3433

3534
- `Installation`_
3635
- `Quickstart`_
36+
- `Examples`_
3737
- `Configuring the Exporter`_
3838
- `Securing the Exporter`_
3939

@@ -51,10 +51,14 @@ Installation
5151
Prerequisite
5252
~~~~~~~~~~~~
5353
1. Install the snappy c-library
54-
**DEB**: `sudo apt-get install libsnappy-dev`
55-
**RPM**: `sudo yum install libsnappy-devel`
56-
**OSX/Brew**: `brew install snappy`
57-
**Windows**: `pip install python_snappy-0.5-cp36-cp36m-win_amd64.whl`
54+
**DEB**: ``sudo apt-get install libsnappy-dev``
55+
56+
**RPM**: ``sudo yum install libsnappy-devel``
57+
58+
**OSX/Brew**: ``brew install snappy``
59+
60+
**Windows**: ``pip install python_snappy-0.5-cp36-cp36m-win_amd64.whl``
61+
5862
2. Install python-snappy
5963
`pip install python-snappy`
6064

@@ -86,6 +90,68 @@ Quickstart
8690
8791
metrics.get_meter_provider().start_pipeline(meter, exporter, 5)
8892
93+
94+
Examples
95+
--------
96+
97+
This example uses `Docker Compose`_ to set up:
98+
99+
1. A Python program that creates 5 instruments with 5 unique aggregators
100+
and a randomized load generator
101+
2. An instance of `Cortex`_ to recieve the metrics data
102+
3. An instance of `Grafana`_ to visualizse the exported data
103+
104+
Requirements
105+
~~~~~~~~~~~~
106+
107+
- Have Docker Compose `installed`_
108+
109+
*Users do not need to install Python as the app will be run in the
110+
Docker Container*
111+
112+
Instructions
113+
~~~~~~~~~~~~
114+
115+
1. Run ``docker-compose up -d`` in the the ``examples/`` directory
116+
117+
The ``-d`` flag causes all services to run in detached mode and frees up
118+
your terminal session. This also causes no logs to show up. Users can
119+
attach themselves to the service’s logs manually using
120+
``docker logs ${CONTAINER_ID} --follow``
121+
122+
2. Log into the Grafana instance at http://localhost:3000
123+
124+
- login credentials are ``username: admin`` and ``password: admin``
125+
- There may be an additional screen on setting a new password. This
126+
can be skipped and is optional
127+
128+
3. Navigate to the ``Data Sources`` page
129+
130+
- Look for a gear icon on the left sidebar and select
131+
``Data Sources``
132+
133+
4. Add a new Prometheus Data Source
134+
135+
- Use ``http://cortex:9009/api/prom`` as the URL
136+
- Set the scrape interval to ``2s`` to make updates
137+
appear quickly **(Optional)**
138+
- click ``Save & Test``
139+
140+
5. Go to ``Metrics Explore`` to query metrics
141+
142+
- Look for a compass icon on the left sidebar
143+
- click ``Metrics`` for a dropdown list of all the available metrics
144+
- Adjust time range by clicking the ``Last 6 hours``
145+
button on the upper right side of the graph **(Optional)**
146+
- Set up auto-refresh by selecting an option under the
147+
dropdown next to the refresh button on the upper right side of the
148+
graph **(Optional)**
149+
- Click the refresh button and data should show up on hte graph
150+
151+
6. Shutdown the services when finished
152+
153+
- Run ``docker-compose down`` in the examples directory
154+
89155
Configuring the Exporter
90156
------------------------
91157

@@ -170,17 +236,24 @@ and key files in the ``tls_config`` parameter.
170236
Supported Aggregators
171237
---------------------
172238
Behaviour of these aggregators is outlined in the `OpenTelemetry Specification <https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md#aggregations>`_.
173-
174-
- Sum
175-
- MinMaxSumCount
176-
- Histogram
177-
- LastValue
178-
- ValueObserver
179-
180239
All aggregators are converted into the `timeseries`_ data format. However, method in
181240
which they are converted `differs <https://github.com/open-telemetry/opentelemetry-python-contrib/blob/master/exporter/opentelemetry-exporter-prometheus-remote-write/src/opentelemetry/exporter/prometheus_remote_write/__init__.py#L196>`_ from aggregator to aggregator. A
182241
map of the conversion methods can be found `here <https://github.com/open-telemetry/opentelemetry-python-contrib/blob/master/exporter/opentelemetry-exporter-prometheus-remote-write/src/opentelemetry/exporter/prometheus_remote_write/__init__.py#L75>`_.
183242

243+
+------------------------------+-------------------------------------+------------------------------------------------------------------------------------------------------------+
244+
| **OpenTelemetry Aggregator** | **Equivalent Prometheus Data Type** | **Behaviour** |
245+
+------------------------------+-------------------------------------+------------------------------------------------------------------------------------------------------------+
246+
| Sum | Counter | Metric value can only go up or be reset to 0 |
247+
+------------------------------+-------------------------------------+------------------------------------------------------------------------------------------------------------+
248+
| MinMaxSumCount | Gauge | Metric value can arbitrarily increment or decrement |
249+
+------------------------------+-------------------------------------+------------------------------------------------------------------------------------------------------------+
250+
| Histogram | Histogram | Unlike the Prometheus histogram, the OpenTelemetry Histogram does not provide a sum of all observed values |
251+
+------------------------------+-------------------------------------+------------------------------------------------------------------------------------------------------------+
252+
| LastValue | N/A | Metric only contains the most recently observed value |
253+
+------------------------------+-------------------------------------+------------------------------------------------------------------------------------------------------------+
254+
| ValueObserver | N/A | Similar to MinMaxSumCount but also contains LastValue |
255+
+------------------------------+-------------------------------------+------------------------------------------------------------------------------------------------------------+
256+
184257

185258
Error Handling
186259
--------------
@@ -225,6 +298,7 @@ significantly increase the size of this repo.
225298
.. _Table of Contents: #table-of-contents
226299
.. _Installation: #installation
227300
.. _Quickstart: #quickstart
301+
.. _Examples: #examples
228302
.. _Configuring the Exporter: #configuring-the-exporter
229303
.. _Securing the Exporter: #securing-the-exporter
230304
.. _Authentication: #authentication
@@ -234,7 +308,6 @@ significantly increase the size of this repo.
234308
.. _Contributing: #contributing
235309
.. _Design Doc: #design-doc
236310
.. |Prometheus SDK pipelines| image:: https://user-images.githubusercontent.com/20804975/100285430-e320fd80-2f3e-11eb-8217-a562c559153c.png
237-
.. |controller_datapath_final| image:: https://user-images.githubusercontent.com/20804975/100486582-79d1f380-30d2-11eb-8d17-d3e58e5c34e9.png
238311
.. _RFC 7617: https://tools.ietf.org/html/rfc7617
239312
.. _RFC 6750: https://tools.ietf.org/html/rfc6750
240313
.. _Design Document: https://github.com/open-o11y/docs/blob/master/python-prometheus-remote-write/design-doc.md
@@ -246,3 +319,7 @@ significantly increase the size of this repo.
246319
.. _remote.proto: https://github.com/prometheus/prometheus/blob/master/prompb/remote.proto
247320
.. _push controller: https://github.com/open-telemetry/opentelemetry-python/blob/master/opentelemetry-sdk/src/opentelemetry/sdk/metrics/export/controller.py#L22
248321
.. _timeseries: https://prometheus.io/docs/concepts/data_model/
322+
.. _Docker Compose: https://docs.docker.com/compose/
323+
.. _Cortex: https://cortexmetrics.io/
324+
.. _Grafana: https://grafana.com/
325+
.. _installed: https://docs.docker.com/compose/install/

0 commit comments

Comments
 (0)