Metadata-Version: 2.1
Name: itrsstatsd
Version: 2.0.0
Summary: ITRS StatsD Client
Home-page: https://www.itrsgroup.com
Author: ITRS Group Ltd.
Author-email: support@itrsgroup.com
License: BSD
Keywords: itrs statsd geneos apm
Platform: UNKNOWN
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python 
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: System :: Monitoring
Classifier: Intended Audience :: Developers
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# itrsstatsd

[![PyPI Version](https://img.shields.io/pypi/v/itrsstatsd)](https://pypi.org/project/itrsstatsd)

Python module for publishing custom metrics to an ITRS StatsD server.

The module is part of the [Orchestrated Netprobe][1] solution for collecting metrics in orchestrated environments.
See the [docs][1] for complete details.

## Requirements
- Python 3.7

## Installation

The module is available via PyPI:
```
pip3 install itrsstatsd
```

## Module Documentation

How to get and use a statsd API handle:  
```
pydoc3 itrsstatsd  
```

API documentation:  
```
pydoc3 itrsstatsd.api
```

Units of measure documentation:
```  
pydoc3 itrsstatsd.units
```

## Getting Started

```python
from itrsstatsd import build_statsd
from itrsstatsd.units import Unit
from itrsstatsd.severity import Severity

# Create an instance of the client that sends to localhost:8125
statsd = build_statsd()

# Optionally add dimension(s) to all metrics
statsd.default_dimensions(app_name="pyapp")

# Record some metrics
statsd.increment("failed_logins")
statsd.gauge("cache_size", 52.5, Unit.Megabytes)
statsd.timer("query_time", 56)
statsd.event("event_name_1", "event_message", Severity.INFO)
statsd.attribute("attr_name_1", "A1")
```

Refer to the pydoc for complete usage details.

[1]: https://docs.itrsgroup.com/docs/orchestrated-netprobe

# Change Log

## v2.0.0 (2020-04-01)

New Features:
- C2-76:  Added event and attribute support
- C2-124: Added new units of measure


## v1.4.0 (2019-12-20)

New Features:
- C2-92: StatsD configuration via environment variables

  This introduces the following changes:
  - **Breaking**: `STATSD_SERVER` and `STATSD_PORT` environment variables now have precedence over the hostname
    and port configured in code.
  - New `STATSD_PROTOCOL` environment variable which can be set to `tcp` or `udp` and overrides the protocol 
    configured in code.
  - New `STATSD_DISABLE_PLATFORM_DIMENSIONS` environment variable which, if `true`, will prevent the platform-specific 
    dimensions from being added to each metric.  This overrides the value configured in code.
  - Custom dimensions can be configured via `STATSD_DIMENSION_*` environment variable(s).

Resolved: 
- C2-98: StatsD client blocks when connecting to server via TCP


## v1.3.0 (2019-09-11)

New Features:
- License changed to BSD 3-Clause
- C2-77: Nano and micro resolution in timer metrics

Resolved:
- C2-78: Statsd client sends malformed message with sample rate


## v1.2.0 (2019-08-23)

New Features:
- C2-72: Discard oldest metrics when sending queue full


## v1.1.0 (2019-08-23)

New Features:
- C2-69: Statsd over TCP


## v1.0.0 (2019-08-15)

First version.


