-
Notifications
You must be signed in to change notification settings - Fork 306
/
base.py
1551 lines (1292 loc) · 56.9 KB
/
base.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#!/usr/bin/env python
# Unless explicitly stated otherwise all files in this repository are licensed under
# the BSD-3-Clause License. This product includes software developed at Datadog
# (https://www.datadoghq.com/).
# Copyright 2015-Present Datadog, Inc
"""
DogStatsd is a Python client for DogStatsd, a Statsd fork for Datadog.
"""
# Standard libraries
from random import random
import logging
import os
import socket
import errno
import threading
import time
from threading import Lock, RLock
import weakref
try:
import queue
except ImportError:
# pypy has the same module, but capitalized.
import Queue as queue # type: ignore[no-redef]
# pylint: disable=unused-import
from typing import Optional, List, Text, Union
# pylint: enable=unused-import
# Datadog libraries
from datadog.dogstatsd.aggregator import Aggregator
from datadog.dogstatsd.metric_types import MetricType
from datadog.dogstatsd.context import (
TimedContextManagerDecorator,
DistributedContextManagerDecorator,
)
from datadog.dogstatsd.route import get_default_route
from datadog.dogstatsd.container import Cgroup
from datadog.util.compat import is_p3k, text
from datadog.util.format import normalize_tags
from datadog.version import __version__
# Logging
log = logging.getLogger("datadog.dogstatsd")
# Default config
DEFAULT_HOST = "localhost"
DEFAULT_PORT = 8125
# Buffering-related values (in seconds)
DEFAULT_BUFFERING_FLUSH_INTERVAL = 0.3
MIN_FLUSH_INTERVAL = 0.0001
# Env var to enable/disable sending the container ID field
ORIGIN_DETECTION_ENABLED = "DD_ORIGIN_DETECTION_ENABLED"
# Environment variable containing external data used for Origin Detection.
EXTERNAL_DATA_ENV_VAR = "DD_EXTERNAL_ENV"
# Default buffer settings based on socket type
UDP_OPTIMAL_PAYLOAD_LENGTH = 1432
UDS_OPTIMAL_PAYLOAD_LENGTH = 8192
# Socket options
MIN_SEND_BUFFER_SIZE = 32 * 1024
# Mapping of each "DD_" prefixed environment variable to a specific tag name
DD_ENV_TAGS_MAPPING = {
"DD_ENTITY_ID": "dd.internal.entity_id",
"DD_ENV": "env",
"DD_SERVICE": "service",
"DD_VERSION": "version",
}
# Telemetry minimum flush interval in seconds
DEFAULT_TELEMETRY_MIN_FLUSH_INTERVAL = 10
# Telemetry pre-computed formatting string. Pre-computation
# increases throughput of composing the result by 2-15% from basic
# '%'-based formatting with a `join`.
TELEMETRY_FORMATTING_STR = "\n".join(
[
"datadog.dogstatsd.client.metrics:%s|c|#%s",
"datadog.dogstatsd.client.events:%s|c|#%s",
"datadog.dogstatsd.client.service_checks:%s|c|#%s",
"datadog.dogstatsd.client.bytes_sent:%s|c|#%s",
"datadog.dogstatsd.client.bytes_dropped:%s|c|#%s",
"datadog.dogstatsd.client.bytes_dropped_queue:%s|c|#%s",
"datadog.dogstatsd.client.bytes_dropped_writer:%s|c|#%s",
"datadog.dogstatsd.client.packets_sent:%s|c|#%s",
"datadog.dogstatsd.client.packets_dropped:%s|c|#%s",
"datadog.dogstatsd.client.packets_dropped_queue:%s|c|#%s",
"datadog.dogstatsd.client.packets_dropped_writer:%s|c|#%s",
]
) + "\n"
Stop = object()
SUPPORTS_FORKING = hasattr(os, "register_at_fork") and not os.environ.get("DD_DOGSTATSD_DISABLE_FORK_SUPPORT", None)
TRACK_INSTANCES = not os.environ.get("DD_DOGSTATSD_DISABLE_INSTANCE_TRACKING", None)
_instances = weakref.WeakSet() # type: weakref.WeakSet
def pre_fork():
"""Prepare all client instances for a process fork.
If SUPPORTS_FORKING is true, this will be called automatically before os.fork().
"""
for c in _instances:
c.pre_fork()
def post_fork_parent():
"""Restore all client instances after a fork.
If SUPPORTS_FORKING is true, this will be called automatically after os.fork().
"""
for c in _instances:
c.post_fork_parent()
def post_fork_child():
for c in _instances:
c.post_fork_child()
if SUPPORTS_FORKING:
os.register_at_fork( # type: ignore
before=pre_fork,
after_in_child=post_fork_child,
after_in_parent=post_fork_parent,
)
# pylint: disable=useless-object-inheritance,too-many-instance-attributes
# pylint: disable=too-many-arguments,too-many-locals
class DogStatsd(object):
OK, WARNING, CRITICAL, UNKNOWN = (0, 1, 2, 3)
def __init__(
self,
host=DEFAULT_HOST, # type: Text
port=DEFAULT_PORT, # type: int
max_buffer_size=None, # type: None
flush_interval=DEFAULT_BUFFERING_FLUSH_INTERVAL, # type: float
disable_aggregation=True, # type: bool
disable_buffering=True, # type: bool
namespace=None, # type: Optional[Text]
constant_tags=None, # type: Optional[List[str]]
use_ms=False, # type: bool
use_default_route=False, # type: bool
socket_path=None, # type: Optional[Text]
default_sample_rate=1, # type: float
disable_telemetry=False, # type: bool
telemetry_min_flush_interval=(DEFAULT_TELEMETRY_MIN_FLUSH_INTERVAL), # type: int
telemetry_host=None, # type: Text
telemetry_port=None, # type: Union[str, int]
telemetry_socket_path=None, # type: Text
max_buffer_len=0, # type: int
container_id=None, # type: Optional[Text]
origin_detection_enabled=True, # type: bool
socket_timeout=0, # type: Optional[float]
telemetry_socket_timeout=0, # type: Optional[float]
disable_background_sender=True, # type: bool
sender_queue_size=0, # type: int
sender_queue_timeout=0, # type: Optional[float]
track_instance=True, # type: bool
): # type: (...) -> None
"""
Initialize a DogStatsd object.
>>> statsd = DogStatsd()
:envvar DD_AGENT_HOST: the host of the DogStatsd server.
If set, it overrides default value.
:type DD_AGENT_HOST: string
:envvar DD_DOGSTATSD_PORT: the port of the DogStatsd server.
If set, it overrides default value.
:type DD_DOGSTATSD_PORT: integer
:envvar DATADOG_TAGS: Tags to attach to every metric reported by dogstatsd client.
:type DATADOG_TAGS: comma-delimited string
:envvar DD_ENTITY_ID: Tag to identify the client entity.
:type DD_ENTITY_ID: string
:envvar DD_ENV: the env of the service running the dogstatsd client.
If set, it is appended to the constant (global) tags of the statsd client.
:type DD_ENV: string
:envvar DD_SERVICE: the name of the service running the dogstatsd client.
If set, it is appended to the constant (global) tags of the statsd client.
:type DD_SERVICE: string
:envvar DD_VERSION: the version of the service running the dogstatsd client.
If set, it is appended to the constant (global) tags of the statsd client.
:type DD_VERSION: string
:envvar DD_DOGSTATSD_DISABLE: Disable any statsd metric collection (default False)
:type DD_DOGSTATSD_DISABLE: boolean
:envvar DD_TELEMETRY_HOST: the host for the dogstatsd server we wish to submit
telemetry stats to. If set, it overrides default value.
:type DD_TELEMETRY_HOST: string
:envvar DD_TELEMETRY_PORT: the port for the dogstatsd server we wish to submit
telemetry stats to. If set, it overrides default value.
:type DD_TELEMETRY_PORT: integer
:envvar DD_ORIGIN_DETECTION_ENABLED: Enable/disable sending the container ID field
for origin detection.
:type DD_ORIGIN_DETECTION_ENABLED: boolean
:envvar DD_DOGSTATSD_DISABLE_FORK_SUPPORT: Don't install global fork hooks with os.register_at_fork.
Global fork hooks then need to be called manually before and after calling os.fork.
:type DD_DOGSTATSD_DISABLE_FORK_SUPPORT: boolean
:envvar DD_DOGSTATSD_DISABLE_INSTANCE_TRACKING: Don't register instances of this class with global fork hooks.
:type DD_DOGSTATSD_DISABLE_INSTANCE_TRACKING: boolean
:param host: the host of the DogStatsd server.
:type host: string
:param port: the port of the DogStatsd server.
:type port: integer
:max_buffer_size: Deprecated option, do not use it anymore.
:type max_buffer_type: None
:flush_interval: Amount of time in seconds that the flush thread will
wait before trying to flush the buffered metrics to the server. If set,
it overrides the default value.
:type flush_interval: float
:disable_aggregation: If true, metrics (Count, Gauge, Set) are no longered aggregated by the client
:type disable_aggregation: bool
:disable_buffering: If set, metrics are no longered buffered by the client and
all data is sent synchronously to the server
:type disable_buffering: bool
:param namespace: Namespace to prefix all metric names
:type namespace: string
:param constant_tags: Tags to attach to all metrics
:type constant_tags: list of strings
:param use_ms: Report timed values in milliseconds instead of seconds (default False)
:type use_ms: boolean
:param use_default_route: Dynamically set the DogStatsd host to the default route
(Useful when running the client in a container) (Linux only)
:type use_default_route: boolean
:param socket_path: Communicate with dogstatsd through a UNIX socket instead of
UDP. If set, disables UDP transmission (Linux only)
:type socket_path: string
:param default_sample_rate: Sample rate to use by default for all metrics
:type default_sample_rate: float
:param max_buffer_len: Maximum number of bytes to buffer before sending to the server
if sending metrics in batch. If not specified it will be adjusted to a optimal value
depending on the connection type.
:type max_buffer_len: integer
:param disable_telemetry: Should client telemetry be disabled
:type disable_telemetry: boolean
:param telemetry_min_flush_interval: Minimum flush interval for telemetry in seconds
:type telemetry_min_flush_interval: integer
:param telemetry_host: the host for the dogstatsd server we wish to submit
telemetry stats to. Optional. If telemetry is enabled and this is not specified
the default host will be used.
:type host: string
:param telemetry_port: the port for the dogstatsd server we wish to submit
telemetry stats to. Optional. If telemetry is enabled and this is not specified
the default host will be used.
:type port: integer
:param telemetry_socket_path: Submit client telemetry to dogstatsd through a UNIX
socket instead of UDP. If set, disables UDP transmission (Linux only)
:type telemetry_socket_path: string
:param container_id: Allows passing the container ID, this will be used by the Agent to enrich
metrics with container tags.
This feature requires Datadog Agent version >=6.35.0 && <7.0.0 or Agent versions >=7.35.0.
When configured, the provided container ID is prioritized over the container ID discovered
via Origin Detection.
Default: None.
:type container_id: string
:param origin_detection_enabled: Enable/disable the client origin detection.
This feature requires Datadog Agent version >=6.35.0 && <7.0.0 or Agent versions >=7.35.0.
When enabled, the client tries to discover its container ID and sends it to the Agent
to enrich the metrics with container tags.
Origin detection can be disabled by configuring the environment variabe DD_ORIGIN_DETECTION_ENABLED=false
The client tries to read the container ID by parsing the file /proc/self/cgroup.
This is not supported on Windows.
Default: True.
More on this: https://docs.datadoghq.com/developers/dogstatsd/?tab=kubernetes#origin-detection-over-udp
:type origin_detection_enabled: boolean
:param socket_timeout: Set timeout for socket operations, in seconds. Optional.
If sets to zero, never wait if operation can not be completed immediately. If set to None, wait forever.
This option does not affect hostname resolution when using UDP.
:type socket_timeout: float
:param telemetry_socket_timeout: Set timeout for the telemetry socket operations. Optional.
Effective only if either telemetry_host or telemetry_socket_path are set.
If sets to zero, never wait if operation can not be completed immediately. If set to None, wait forever.
This option does not affect hostname resolution when using UDP.
:type telemetry_socket_timeout: float
:param disable_background_sender: Use a background thread to communicate with the dogstatsd server. Optional.
When enabled, a background thread will be used to send metric payloads to the Agent.
Applications should call stop() before exiting to make sure all pending payloads are sent.
Default: True.
:type disable_background_sender: boolean
:param sender_queue_size: Set the maximum number of packets to queue for the sender. Optional
How may packets to queue before blocking or dropping the packet if the packet queue is already full.
Default: 0 (unlimited).
:type sender_queue_size: integer
:param sender_queue_timeout: Set timeout for packet queue operations, in seconds. Optional.
How long the application thread is willing to wait for the queue clear up before dropping the metric packet.
If set to None, wait forever.
If set to zero drop the packet immediately if the queue is full.
Default: 0 (no wait)
:type sender_queue_timeout: float
:param track_instance: Keep track of this instance and automatically handle cleanup when os.fork() is called,
if supported.
Default: True.
:type track_instance: boolean
"""
self._socket_lock = Lock()
# Check for deprecated option
if max_buffer_size is not None:
log.warning("The parameter max_buffer_size is now deprecated and is not used anymore")
# Check host and port env vars
agent_host = os.environ.get("DD_AGENT_HOST")
if agent_host and host == DEFAULT_HOST:
host = agent_host
dogstatsd_port = os.environ.get("DD_DOGSTATSD_PORT")
if dogstatsd_port and port == DEFAULT_PORT:
try:
port = int(dogstatsd_port)
except ValueError:
log.warning(
"Port number provided in DD_DOGSTATSD_PORT env var is not an integer: \
%s, using %s as port number",
dogstatsd_port,
port,
)
# Assuming environment variables always override
telemetry_host = os.environ.get("DD_TELEMETRY_HOST", telemetry_host)
telemetry_port = os.environ.get("DD_TELEMETRY_PORT", telemetry_port) or port
# Check enabled
if os.environ.get("DD_DOGSTATSD_DISABLE") not in {"True", "true", "yes", "1"}:
self._enabled = True
else:
self._enabled = False
# Connection
self._max_buffer_len = max_buffer_len
self.socket_timeout = socket_timeout
if socket_path is not None:
self.socket_path = socket_path # type: Optional[text]
self.host = None
self.port = None
else:
self.socket_path = None
self.host = self.resolve_host(host, use_default_route)
self.port = int(port)
self.telemetry_socket_path = telemetry_socket_path
self.telemetry_host = None
self.telemetry_port = None
self.telemetry_socket_timeout = telemetry_socket_timeout
if not telemetry_socket_path and telemetry_host:
self.telemetry_socket_path = None
self.telemetry_host = self.resolve_host(telemetry_host, use_default_route)
self.telemetry_port = int(telemetry_port)
# Socket
self.socket = None
self.telemetry_socket = None
self.encoding = "utf-8"
# Options
env_tags = [tag for tag in os.environ.get("DATADOG_TAGS", "").split(",") if tag]
# Inject values of DD_* environment variables as global tags.
for var, tag_name in DD_ENV_TAGS_MAPPING.items():
value = os.environ.get(var, "")
if value:
env_tags.append("{name}:{value}".format(name=tag_name, value=value))
if constant_tags is None:
constant_tags = []
self.constant_tags = constant_tags + env_tags
if namespace is not None:
namespace = text(namespace)
self.namespace = namespace
self.use_ms = use_ms
self.default_sample_rate = default_sample_rate
# Origin detection
self._container_id = None
origin_detection_enabled = self._is_origin_detection_enabled(
container_id, origin_detection_enabled
)
self._set_container_id(container_id, origin_detection_enabled)
self._external_data = os.environ.get(EXTERNAL_DATA_ENV_VAR, None)
# init telemetry version
self._client_tags = [
"client:py",
"client_version:{}".format(__version__),
]
self._reset_telemetry()
self._telemetry_flush_interval = telemetry_min_flush_interval
self._telemetry = not disable_telemetry
self._last_flush_time = time.time()
self._current_buffer_total_size = 0
self._buffer = [] # type: List[Text]
self._buffer_lock = RLock()
self._reset_buffer()
# This lock is used for all cases where client configuration is being changed: buffering,
# aggregation, sender mode.
self._config_lock = RLock()
self._disable_buffering = disable_buffering
self._disable_aggregation = disable_aggregation
self._flush_interval = flush_interval
self._flush_thread = None
self._flush_thread_stop = threading.Event()
self.aggregator = Aggregator()
# Indicates if the process is about to fork, so we shouldn't start any new threads yet.
self._forking = False
if not self._disable_buffering:
self._send = self._send_to_buffer
else:
self._send = self._send_to_server
if not self._disable_aggregation or not self._disable_buffering:
self._start_flush_thread()
else:
log.debug("Statsd buffering and aggregation is disabled")
self._queue = None
self._sender_thread = None
self._sender_enabled = False
if not disable_background_sender:
self.enable_background_sender(sender_queue_size, sender_queue_timeout)
if TRACK_INSTANCES and track_instance:
_instances.add(self)
@property
def socket_path(self):
return self._socket_path
@socket_path.setter
def socket_path(self, path):
with self._socket_lock:
self._socket_path = path
if path is None:
self._transport = "udp"
self._max_payload_size = self._max_buffer_len or UDP_OPTIMAL_PAYLOAD_LENGTH
else:
self._transport = "uds"
self._max_payload_size = self._max_buffer_len or UDS_OPTIMAL_PAYLOAD_LENGTH
def enable_background_sender(self, sender_queue_size=0, sender_queue_timeout=0):
"""
Use a background thread to communicate with the dogstatsd server.
When enabled, a background thread will be used to send metric payloads to the Agent.
Applications should call stop() before exiting to make sure all pending payloads are sent.
Compatible with os.fork() starting with Python 3.7. On earlier versions, compatible if applications
arrange to call pre_fork(), post_fork_parent() and post_fork_child() module functions around calls
to os.fork().
:param sender_queue_size: Set the maximum number of packets to queue for the sender.
How many packets to queue before blocking or dropping the packet if the packet queue is already full.
Default: 0 (unlimited).
:type sender_queue_size: integer, optional
:param sender_queue_timeout: Set timeout for packet queue operations, in seconds.
How long the application thread is willing to wait for the queue clear up before dropping the metric packet.
If set to None, wait forever. If set to zero drop the packet immediately if the queue is full.
Default: 0 (no wait).
:type sender_queue_timeout: float, optional
"""
with self._config_lock:
self._sender_enabled = True
self._sender_queue_size = sender_queue_size
if sender_queue_timeout is None:
self._queue_blocking = True
self._queue_timeout = None
else:
self._queue_blocking = sender_queue_timeout > 0
self._queue_timeout = max(0, sender_queue_timeout)
self._start_sender_thread()
def disable_background_sender(self):
"""Disable background sender mode.
This call will block until all previously queued payloads are sent.
"""
with self._config_lock:
self._sender_enabled = False
self._stop_sender_thread()
def disable_telemetry(self):
self._telemetry = False
def enable_telemetry(self):
self._telemetry = True
# Note: Invocations of this method should be thread-safe
def _start_flush_thread(self):
if self._disable_aggregation and self.disable_buffering:
log.debug("Statsd periodic buffer and aggregation flush is disabled")
return
if self._flush_interval <= MIN_FLUSH_INTERVAL:
log.debug(
"the set flush interval is less then the minimum"
)
return
if self._forking:
return
if self._flush_thread is not None:
return
def _flush_thread_loop(self, flush_interval):
while not self._flush_thread_stop.is_set():
time.sleep(flush_interval)
if not self._disable_aggregation:
self.flush_aggregated_metrics()
if not self._disable_buffering:
self.flush_buffered_metrics()
self._flush_thread = threading.Thread(
name="{}_flush_thread".format(self.__class__.__name__),
target=_flush_thread_loop,
args=(self, self._flush_interval,),
)
self._flush_thread.daemon = True
self._flush_thread.start()
log.debug(
"Statsd flush thread registered with period of %s",
self._flush_interval,
)
# Note: Invocations of this method should be thread-safe
def _stop_flush_thread(self):
if not self._flush_thread:
return
try:
if not self._disable_aggregation:
self.flush_aggregated_metrics()
if not self.disable_buffering:
self.flush_buffered_metrics()
finally:
pass
self._flush_thread_stop.set()
self._flush_thread.join()
self._flush_thread = None
self._flush_thread_stop.clear()
def _dedicated_telemetry_destination(self):
return bool(self.telemetry_socket_path or self.telemetry_host)
# Context manager helper
def __enter__(self):
self.open_buffer()
return self
# Context manager helper
def __exit__(self, exc_type, value, traceback):
self.close_buffer()
@property
def disable_buffering(self):
with self._config_lock:
return self._disable_buffering
@disable_buffering.setter
def disable_buffering(self, is_disabled):
with self._config_lock:
# If the toggle didn't change anything, this method is a noop
if self._disable_buffering == is_disabled:
return
self._disable_buffering = is_disabled
# If buffering (and aggregation) has been disabled, flush and kill the background thread
# otherwise start up the flushing thread and enable the buffering.
if is_disabled:
self._send = self._send_to_server
if self._disable_aggregation and self.disable_buffering:
self._stop_flush_thread()
log.debug("Statsd buffering is disabled")
else:
self._send = self._send_to_buffer
self._start_flush_thread()
def disable_aggregation(self):
with self._config_lock:
# If the toggle didn't change anything, this method is a noop
if self._disable_aggregation:
return
self._disable_aggregation = True
# If aggregation and buffering has been disabled, flush and kill the background thread
# otherwise start up the flushing thread and enable aggregation.
if self._disable_aggregation and self.disable_buffering:
self._stop_flush_thread()
log.debug("Statsd aggregation is disabled")
def enable_aggregation(self, flush_interval=DEFAULT_BUFFERING_FLUSH_INTERVAL):
with self._config_lock:
if not self._disable_aggregation:
return
self._disable_aggregation = False
self._flush_interval = flush_interval
if self._disable_buffering:
self._send = self._send_to_server
self._start_flush_thread()
@staticmethod
def resolve_host(host, use_default_route):
"""
Resolve the DogStatsd host.
:param host: host
:type host: string
:param use_default_route: Use the system default route as host (overrides `host` parameter)
:type use_default_route: bool
"""
if not use_default_route:
return host
return get_default_route()
def get_socket(self, telemetry=False):
"""
Return a connected socket.
Note: connect the socket before assigning it to the class instance to
avoid bad thread race conditions.
"""
with self._socket_lock:
if telemetry and self._dedicated_telemetry_destination():
if not self.telemetry_socket:
if self.telemetry_socket_path is not None:
self.telemetry_socket = self._get_uds_socket(
self.telemetry_socket_path,
self.telemetry_socket_timeout,
)
else:
self.telemetry_socket = self._get_udp_socket(
self.telemetry_host,
self.telemetry_port,
self.telemetry_socket_timeout,
)
return self.telemetry_socket
if not self.socket:
if self.socket_path is not None:
self.socket = self._get_uds_socket(self.socket_path, self.socket_timeout)
else:
self.socket = self._get_udp_socket(
self.host,
self.port,
self.socket_timeout,
)
return self.socket
def set_socket_timeout(self, timeout):
"""
Set timeout for socket operations, in seconds.
If set to zero, never wait if operation can not be completed immediately. If set to None, wait forever.
This option does not affect hostname resolution when using UDP.
"""
with self._socket_lock:
self.socket_timeout = timeout
if self.socket:
self.socket.settimeout(timeout)
@classmethod
def _ensure_min_send_buffer_size(cls, sock, min_size=MIN_SEND_BUFFER_SIZE):
# Increase the receiving buffer size where needed (e.g. MacOS has 4k RX
# buffers which is half of the max packet size that the client will send.
if os.name == 'posix':
try:
recv_buff_size = sock.getsockopt(socket.SOL_SOCKET, socket.SO_SNDBUF)
if recv_buff_size <= min_size:
sock.setsockopt(socket.SOL_SOCKET, socket.SO_SNDBUF, min_size)
log.debug("Socket send buffer increased to %dkb", min_size / 1024)
finally:
pass
@classmethod
def _get_uds_socket(cls, socket_path, timeout):
sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
sock.settimeout(timeout)
cls._ensure_min_send_buffer_size(sock)
sock.connect(socket_path)
return sock
@classmethod
def _get_udp_socket(cls, host, port, timeout):
log.debug("Connecting to %s:%s", host, port)
addrinfo = socket.getaddrinfo(host, port, 0, socket.SOCK_DGRAM)
# Override gai.conf order for backwrads compatibility: prefer
# v4, so that a v4-only service on hosts with both addresses
# still works.
addrinfo.sort(key=lambda v: v[0] == socket.AF_INET, reverse=True)
lastaddr = len(addrinfo) - 1
for i, (af, ty, proto, _, addr) in enumerate(addrinfo):
sock = None
try:
sock = socket.socket(af, ty, proto)
sock.settimeout(timeout)
cls._ensure_min_send_buffer_size(sock)
sock.connect(addr)
log.debug("Connected to: %s", addr)
return sock
except Exception as e:
if sock is not None:
sock.close()
log.debug("Failed to connect to %s: %s", addr, e)
if i < lastaddr:
continue
raise e
else:
raise ValueError("getaddrinfo returned no addresses to connect to")
def open_buffer(self, max_buffer_size=None):
"""
Open a buffer to send a batch of metrics.
To take advantage of automatic flushing, you should use the context manager instead
>>> with DogStatsd() as batch:
>>> batch.gauge("users.online", 123)
>>> batch.gauge("active.connections", 1001)
Note: This method must be called before close_buffer() matching invocation.
"""
self._config_lock.acquire()
self._send = self._send_to_buffer
if max_buffer_size is not None:
log.warning("The parameter max_buffer_size is now deprecated and is not used anymore")
def close_buffer(self):
"""
Flush the buffer and switch back to single metric packets.
Note: This method must be called after a matching open_buffer()
invocation.
"""
try:
self.flush_buffered_metrics()
finally:
if self._disable_buffering:
self._send = self._send_to_server
self._config_lock.release()
def _reset_buffer(self):
with self._buffer_lock:
self._current_buffer_total_size = 0
self._buffer = []
def flush(self):
self.flush_buffered_metrics()
def flush_buffered_metrics(self):
"""
Flush the metrics buffer by sending the data to the server.
"""
with self._buffer_lock:
# Only send packets if there are packets to send
if self._buffer:
self._send_to_server("\n".join(self._buffer))
self._reset_buffer()
def flush_aggregated_metrics(self):
"""
Flush the aggregated metrics
"""
metrics = self.aggregator.flush_aggregated_metrics()
for m in metrics:
self._report(m.name, m.metric_type, m.value, m.tags, m.rate, m.timestamp)
def gauge(
self,
metric, # type: Text
value, # type: float
tags=None, # type: Optional[List[str]]
sample_rate=None, # type: Optional[float]
): # type(...) -> None
"""
Record the value of a gauge, optionally setting a list of tags and a
sample rate.
>>> statsd.gauge("users.online", 123)
>>> statsd.gauge("active.connections", 1001, tags=["protocol:http"])
"""
if self._disable_aggregation:
self._report(metric, "g", value, tags, sample_rate)
else:
self.aggregator.gauge(metric, value, tags, sample_rate)
# Minimum Datadog Agent version: 7.40.0
def gauge_with_timestamp(
self,
metric, # type: Text
value, # type: float
timestamp, # type: int
tags=None, # type: Optional[List[str]]
sample_rate=None, # type: Optional[float]
): # type(...) -> None
"""u
Record the value of a gauge with a Unix timestamp (in seconds),
optionally setting a list of tags and a sample rate.
Minimum Datadog Agent version: 7.40.0
>>> statsd.gauge("users.online", 123, 1713804588)
>>> statsd.gauge("active.connections", 1001, 1713804588, tags=["protocol:http"])
"""
if self._disable_aggregation:
self._report(metric, "g", value, tags, sample_rate, timestamp)
else:
self.aggregator.gauge(metric, value, tags, sample_rate, timestamp)
def count(
self,
metric, # type: Text
value, # type: float
tags=None, # type: Optional[List[str]]
sample_rate=None, # type: Optional[float]
): # type(...) -> None
"""
Count tracks how many times something happened per second, tags and a sample
rate.
>>> statsd.count("page.views", 123)
"""
if self._disable_aggregation:
self._report(metric, "c", value, tags, sample_rate)
else:
self.aggregator.count(metric, value, tags, sample_rate)
# Minimum Datadog Agent version: 7.40.0
def count_with_timestamp(
self,
metric, # type: Text
value, # type: float
timestamp=0, # type: int
tags=None, # type: Optional[List[str]]
sample_rate=None, # type: Optional[float]
): # type(...) -> None
"""
Count how many times something happened at a given Unix timestamp in seconds,
tags and a sample rate.
Minimum Datadog Agent version: 7.40.0
>>> statsd.count("files.transferred", 124, timestamp=1713804588)
"""
if self._disable_aggregation:
self._report(metric, "c", value, tags, sample_rate, timestamp)
else:
self.aggregator.count(metric, value, tags, sample_rate, timestamp)
def increment(
self,
metric, # type: Text
value=1, # type: float
tags=None, # type: Optional[List[str]]
sample_rate=None, # type: Optional[float]
): # type(...) -> None
"""
Increment a counter, optionally setting a value, tags and a sample
rate.
>>> statsd.increment("page.views")
>>> statsd.increment("files.transferred", 124)
"""
if self._disable_aggregation:
self._report(metric, "c", value, tags, sample_rate)
else:
self.aggregator.count(metric, value, tags, sample_rate)
def decrement(
self,
metric, # type: Text
value=1, # type: float
tags=None, # type: Optional[List[str]]
sample_rate=None, # type: Optional[float]
): # type(...) -> None
"""
Decrement a counter, optionally setting a value, tags and a sample
rate.
>>> statsd.decrement("files.remaining")
>>> statsd.decrement("active.connections", 2)
"""
metric_value = -value if value else value
if self._disable_aggregation:
self._report(metric, "c", metric_value, tags, sample_rate)
else:
self.aggregator.count(metric, metric_value, tags, sample_rate)
def histogram(
self,
metric, # type: Text
value, # type: float
tags=None, # type: Optional[List[str]]
sample_rate=None, # type: Optional[float]
): # type(...) -> None
"""
Sample a histogram value, optionally setting tags and a sample rate.
>>> statsd.histogram("uploaded.file.size", 1445)
>>> statsd.histogram("album.photo.count", 26, tags=["gender:female"])
"""
self._report(metric, "h", value, tags, sample_rate)
def distribution(
self,
metric, # type: Text
value, # type: float
tags=None, # type: Optional[List[str]]
sample_rate=None, # type: Optional[float]
): # type(...) -> None
"""
Send a global distribution value, optionally setting tags and a sample rate.
>>> statsd.distribution("uploaded.file.size", 1445)
>>> statsd.distribution("album.photo.count", 26, tags=["gender:female"])
"""
self._report(metric, "d", value, tags, sample_rate)
def timing(
self,
metric, # type: Text
value, # type: float
tags=None, # type: Optional[List[str]]
sample_rate=None, # type: Optional[float]
): # type(...) -> None
"""
Record a timing, optionally setting tags and a sample rate.
>>> statsd.timing("query.response.time", 1234)
"""
self._report(metric, "ms", value, tags, sample_rate)
def timed(self, metric=None, tags=None, sample_rate=None, use_ms=None):
"""
A decorator or context manager that will measure the distribution of a
function's/context's run time. Optionally specify a list of tags or a
sample rate. If the metric is not defined as a decorator, the module
name and function name will be used. The metric is required as a context
manager.