8000 Copy some README docs into core.py docstrings · samdroid-apps/client_python@4f89b99 · GitHub
[go: up one dir, main page]
Skip to content

Commit 4f89b99

Browse files
logstonlogston
committed
Copy some README docs into core.py docstrings
In an attempt to bolster the docstrings in the core.py file, some of the README docs were copied into the core.py.
1 parent 25694aa commit 4f89b99

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-
A93C 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