8000 Merge pull request #65 from logston/docs-love · pythonAI/client_python@24403c6 · GitHub
[go: up one dir, main page]
Skip to content

Commit 24403c6

Browse files
brian-brazilbrian-brazil
committed
Merge pull request prometheus#65 from logston/docs-love
Copy some README docs into core.py docstrings
2 parents 94c890c + 4f89b99 commit 24403c6

File tree

3 files changed

+105
-39
lines changed

3 files changed

+105
-39
lines changed

‎AUTHORS.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,5 @@ The following individuals have contributed code to this repository
77

88
* Andrea Fagan <andreafagan28@gmail.com>
99
* Brian Brazil <brian.brazil@gmail.com>
10+
* Paul Logston <code@logston.me>
11+

‎README.md

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ pip install prometheus_client
1111

1212
**Two**: Paste the following into a Python interpreter:
1313
```python
14-
from prometheus_client import start_http_server,Summary
14+
from prometheus_client import start_http_server, Summary
1515
import random
1616
import time
1717

@@ -219,6 +219,7 @@ server in a daemon thread on the given port:
219219

220220
```python
221221
from prometheus_client import start_http_server
222+
222223
start_http_server(8000)
223224
```
224225

@@ -238,7 +239,8 @@ about a machine system that the Node exporter does not support or would not make
238239
to perform at every scrape (for example, anything involving subprocesses).
239240

240241
```python
241-
from prometheus_client import CollectorRegistry,Gauge,write_to_textfile
242+
from prometheus_client import CollectorRegistry, Gauge, write_to_textfile
243+
242244
registry = CollectorRegistry()
243245
g = Gauge('raid_status', '1 if raid array is okay', registry=registry)
244246
g.set(1)
@@ -254,7 +256,8 @@ The [Pushgateway](https://github.com/prometheus/pushgateway)
254256
allows ephemeral and batch jobs to expose their metrics to Prometheus.
255257

256258
```python
257-
from prometheus_client import CollectorRegistry,Gauge,push_to_gateway
259+
from prometheus_client import CollectorRegistry, Gauge, push_to_gateway
260+
258261
registry = CollectorRegistry()
259262
g = Gauge('job_last_success_unixtime', 'Last time a batch job successfully finished', registry=registry)
260263
g.set_to_current_time()
@@ -287,6 +290,7 @@ Metrics are pushed over TCP in the Graphite plaintext format.
287290

288291
```python
289292
from prometheus_client.bridge.graphite import GraphiteBridge
293+
290294
gb = GraphiteBridge(('graphite.your.org', 2003))
291295
# Push once.
292296
gb.push()
@@ -332,4 +336,3 @@ for family in text_string_to_metric_families("my_gauge 1.0\n"):
332336
print("Name: {0} Labels: {1} Value: {2}".format(*sample))
333337
```
334338

335-

‎prometheus_client/core.py

Lines changed: 96 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -256,12 +256,25 @@ def __init__(self, wrappedClass, name, labelnames, **kwargs):
256256
def labels(self, *labelvalues):
257257
'''Return the child for the given labelset.
258258
259-
Labels can be provided as a tuple or as a dict:
260-
c = Counter('c', 'counter', ['l', 'm'])
261-
# Set labels by position
262-
c.labels('0', '1').inc()
263-
# Set labels by name
264-
c.labels({'l': '0', 'm': '1'}).inc()
259+
All metrics can have labels, allowing grouping of related time series.
260+
Taking a counter as an example:
261+
262+
from prometheus_client import Counter
263+
264+
c = Counter('my_requests_total', 'HTTP Failures', ['method', 'endpoint'])
265+
c.labels('get', '/').inc()
266+
c.labels('post', '/submit').inc()
267+
268+
Labels can also be provided as a dict:
269+
270+
from prometheus_client import Counter
271+
272+
c = Counter('my_requests_total', 'HTTP Failures', ['method', 'endpoint'])
273+
c.labels({'method': 'get', 'endpoint': '/'}).inc()
274+
c.labels({'method': 'post', 'endpoint': '/submit'}).inc()
275+
276+
See the best practices on [naming](http://prometheus.io/docs/practices/naming/)
277+
and [labels](http://prometheus.io/docs/practices/instrumentation/#use-labels).
265278
'''
266279
if len(labelvalues) == 1 and type(labelvalues[0]) == dict:
267280
if sorted(labelvalues[0].keys()) != sorted(self._labelnames):
@@ -347,10 +360,24 @@ class Counter(object):
347360
348361
An example for a Counter:
349362
350-
from prometheus_client import Counter
351-
c = Counter('my_failures_total', 'Description of counter')
352-
c.inc() # Increment by 1
353-
c.inc(1.6) # Increment by given value
363+
from prometheus_client import Counter
364+
365+
c = Counter('my_failures_total', 'Description of counter')
366+
c.inc() # Increment by 1
367+
c.inc(1.6) # Increment by given value
368+
369+
There are utilities to count exceptions raised:
370+
371+
@c.count_exceptions()
372+
def f():
373+
pass
374+
375+
with c.count_exceptions():
376+
pass
377+
378+
# Count only one type of exception
379+
with c.count_exceptions(ValueError):
380+
pass
354381
'''
355382
_type = 'counter'
356383
_reserved_labelnames = []
@@ -401,19 +428,38 @@ class Gauge(object):
401428
'''Gauge metric, to report instantaneous values.
402429
403430
Examples of Gauges include:
404-
Inprogress requests
405-
Number of items in a queue
406-
Free memory
407-
Total memory
408-
Temperature
431+
- Inprogress requests
432+
- Number of items in a queue
433+
- Free memory
434+
- Total memory
435+
- Temperature
409436
410437
Gauges can go both up and down.
411438
412439
from prometheus_client import Gauge
440+
413441
g = Gauge('my_inprogress_requests', 'Description of gauge')
414442
g.inc() # Increment by 1
415443
g.dec(10) # Decrement by given value
416444
g.set(4.2) # Set to a given value
445+
446+
There are utilities for common use cases:
447+
448+
g.set_to_current_time() # Set to current unixtime
449+
450+
# Increment when entered, decrement when exited.
451+
@g.track_inprogress()
452+
def f():
453+
pass
454+
455+
with g.track_inprogress():
456+
pass
457+
458+
A Gauge can also take its value from a callback:
459+
460+
d = Gauge('data_objects', 'Number of objects')
461+
my_dict = {}
462+
d.set_function(lambda: len(my_dict))
417463
'''
418464
_type = 'gauge'
419465
_reserved_labelnames = []
@@ -494,8 +540,7 @@ def set_function(self, f):
494540
'''Call the provided function to return the Gauge value.
495541
496542
The function must return a float, and may be called from
497-
multiple threads.
498-
All other methods of the Gauge become NOOPs.
543+
multiple threads. All other methods of the Gauge become NOOPs.
499544
'''
500545
def samples(self):
501546
return (('', {}, float(f())), )
@@ -515,19 +560,26 @@ class Summary(object):
515560
516561
Example for a Summary:
517562
518-
from prometheus_client import Summary
519-
s = Summary('request_size_bytes', 'Request size (bytes)')
520-
s.observe(512) # Observe 512 (bytes)
563+
from prometheus_client import Summary
564+
565+
s = Summary('request_size_bytes', 'Request size (bytes)')
566+
s.observe(512) # Observe 512 (bytes)
521567
522568
Example for a Summary using time:
523-
from prometheus_client import Summary
524-
REQUEST_TIME = Summary('response_latency_seconds', 'Response latency (seconds)')
525569
526-
@REQUEST_TIME.time()
527-
def create_response(request):
528-
"""A dummy function"""
529-
time.sleep(1)
570+
from prometheus_client import Summary
571+
572+
REQUEST_TIME = Summary('response_latency_seconds', 'Response latency (seconds)')
573+
574+
@REQUEST_TIME.time()
575+
def create_response(request):
576+
"""A dummy function"""
577+
time.sleep(1)
530578
579+
Example for using the same Summary object as a context manager:
580+
581+
with REQUEST_TIME.time():
582+
pass # Logic to be timed
531583
'''
532584
_type = 'summary'
533585
_reserved_labelnames = ['quantile']
@@ -596,22 +648,31 @@ class Histogram(object):
596648
597649
Example for a Histogram:
598650
599-
from prometheus_client import Histogram
600-
h = Histogram('request_size_bytes', 'Request size (bytes)')
601-
h.observe(512) # Observe 512 (bytes)
651+
from prometheus_client import Histogram
602652
653+
h = Histogram('request_size_bytes', 'Request size (bytes)')
654+
h.observe(512) # Observe 512 (bytes)
603655
604656
Example for a Histogram using time:
605-
from prometheus_client import Histogram
606-
REQUEST_TIME = Histogram('response_latency_seconds', 'Response latency (seconds)')
607657
608-
@REQUEST_TIME.time()
609-
def create_response(request):
610-
"""A dummy function"""
611-
time.sleep(1)
658+
from prometheus_client import Histogram
659+
660+
REQUEST_TIME = Histogram('response_latency_seconds', 'Response latency (seconds)')
661+
662+
@REQUEST_TIME.time()
663+
def create_response(request):
664+
"""A dummy function"""
665+
time.sleep(1)
666+
667+
Example of using the same Histogram object as a context manager:
668+
669+
with REQUEST_TIME.time():
670+
pass # Logic to be timed
612671
613672
The default buckets are intended to cover a typical web/rpc request from milliseconds to seconds.
614673
They can be overridden by passing `buckets` keyword argument to `Histogram`.
674+
675+
**NB** The Python client doesn't store or expose quantile information at this time.
615676
'''
616677
_type = 'histogram'
617678
_reserved_labelnames = ['histogram']

0 commit comments

Comments
 (0)
0