SSWG Metrics Statsd Client Implementation
- Proposal: SSWG-xxxx
- Authors: Tom Doron
- Status: Implemented
- Pitch: Statsd client in swift
Package Description
| Package Name | swift-statsd-client |
| Module Name | StatsdClient |
| Proposed Maturity Level | Sandbox |
| License | Apache 2.0 |
| Dependencies | swift-nio > 1.0.0 - swift-metrics > 1.0.0 |
Introduction
for a background on metrics in swift applications, see the metrics proposal
the statsd protocol is simpler than most custom metrics solutions (eg prometheus), yet extremely popular since it is language agnostic and easy to implement both client and server side. as such, it can be used to integrate applications with many observability solutions such as:
Motivation
a statsd client will allow server applications written in swift to easily integrate with many popular observability solutions. the client, like the protocol, is designed to be lightweight and delegate most computation to the observability server
Proposed solution
the proposed solution is a client library that implements the swift metric api and uses swift nio to establish a UDP connection to the statsd server.
metrics types are mapped as following:
| Metrics API | Statsd |
|---|---|
| Counter | Counter |
| Gauge | Gauge |
| Timer | Timer |
| Recorder | Histogram |
Detailed design
api
the client is primarily designed to be used within the context of the swift metrics api. as such, the application needs to create an instance of the StatsdClient and bootstrap the MertricsSystem as part of the application's main:
let statsdClient = try StatsdClient(host: host, port: port)
MetricsSystem.bootstrap(statsdClient)
to cleanly release the networking resources occupied by the client, the application should also shutdown the client before it terminates:
statsdClient.shutdown()
as mentioned above, usage of the client is designed to be done primarily via the swift metrics api and the client does not provide additional functionality beyond the metrics api surface area. in other words, users are not expected to interact with the client directly beyond bootstrap and shutdown. emitting metrics information is done via the standard metrics api, as described in GitHub - apple/swift-metrics: A Metrics API for Swift
protocol
the client implements the stated protocol as following:
| counter | `: |
| timer | `: |
| gauge | `: |
| histogram | `: |
name is constructed from the metric object label and dimensions concatenated with a dot between them
value is computed from the data provided to the metrics API. no in-memory aggregation is done at the client level, and data is mostly pass-through. note that some statsd metrics types accept positive values only in the UInt64 range, while the metrics API generally accepts Int64. in cases of such mismatch, the client truncates negative values to zero
networking
thew client uses swift-nio to establish a UDP connection to the statsd server. in later phases, the client will also support TCP connections.