{"id":10266,"library":"statsd-tags","title":"StatsD Tags Client","description":"A lightweight Python client for StatsD, extending the basic StatsD protocol with DogStatsD-compatible tags. It simplifies sending metrics with key-value tags to StatsD servers that support the DataDog extension. The current version is 3.2.1.post1, and the project is actively maintained with a stable release cadence.","status":"active","version":"3.2.1.post1","language":"en","source_language":"en","source_url":"https://github.com/toddjames/statsd-tags","tags":["statsd","monitoring","metrics","tags","dogstatsd","observability"],"install":[{"cmd":"pip install statsd-tags","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The main client class `StatsClient` is directly available under the top-level `statsd_tags` package, not within a sub-module like `client`.","wrong":"from statsd_tags.client import StatsClient","symbol":"StatsClient","correct":"from statsd_tags import StatsClient"}],"quickstart":{"code":"import os\nfrom statsd_tags import StatsClient\n\n# Configure host/port via environment variables for easy deployment\nstatsd_host = os.environ.get('STATSD_HOST', 'localhost')\nstatsd_port = int(os.environ.get('STATSD_PORT', '8125'))\n\n# Initialize the StatsD client with a prefix and default tags\nclient = StatsClient(\n    host=statsd_host,\n    port=statsd_port,\n    prefix='my_application',\n    tags={'environment': 'production'}\n)\n\n# Increment a counter metric with additional, specific tags\nclient.incr('request_count', tags={'endpoint': '/api/v1/data', 'status': '200'})\n\n# Set a gauge metric value with custom tags\nclient.gauge('cpu_utilization', 45.7, tags={'server': 'web_01'})\n\n# Record a timing metric (milliseconds) with event-specific tags\nclient.timing('db_query_time', 123.45, tags={'query_type': 'read'})\n\nprint(f\"Sent metrics (incr, gauge, timing) to StatsD at {statsd_host}:{statsd_port}\")\nprint(\"Note: StatsD uses UDP, so there's no direct confirmation of receipt.\")","lang":"python","description":"Initialize the `StatsClient` with a host, port, optional prefix, and default tags. Then use methods like `incr`, `gauge`, and `timing` to send various metric types, providing specific tags for each metric call that override or merge with default client tags."},"warnings":[{"fix":"Ensure your StatsD server (e.g., Datadog Agent, Telegraf with DogStatsD input) is specifically configured to handle DogStatsD-formatted metrics. Test with a simple tagged metric to confirm proper tag processing.","message":"This library is designed to send DogStatsD-compatible tags (e.g., `metric:value|#tag:value`). If your StatsD server (e.g., a vanilla `statsd` daemon or a basic implementation) does not explicitly support DogStatsD extensions, the tags will likely be ignored or cause parsing errors on the server side.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `from statsd_tags import StatsClient` (or other symbols) in your Python code, not `from statsd-tags import ...`.","message":"The PyPI package name for installation is `statsd-tags` (with a hyphen), but the Python importable package name uses underscores: `statsd_tags`. Attempting to import `statsd-tags` will result in a `ModuleNotFoundError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify network connectivity between your application and the StatsD server (e.g., `netcat -u -z <host> <port>`). Ensure no firewalls are blocking UDP traffic on the StatsD port (default 8125). Monitor the StatsD server logs for incoming metrics to confirm receipt.","message":"StatsD typically uses UDP for metric transmission, which is a connectionless protocol. The client will not raise an error if the StatsD server is unreachable, misconfigured, or if packets are dropped by a firewall. Metrics can silently fail to be received.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure the import path matches the installed package, which uses underscores: `from statsd_tags import StatsClient`.","cause":"Incorrect package name or a common typo used in the import statement.","error":"ModuleNotFoundError: No module named 'statsd_tags_client'"},{"fix":"Import the `StatsClient` class directly from the module: `from statsd_tags import StatsClient`.","cause":"The user tried `import statsd_tags` and then attempted to access `statsd_tags.StatsClient` directly, instead of importing the `StatsClient` class explicitly.","error":"AttributeError: module 'statsd_tags' has no attribute 'StatsClient'"}]}