Swift Dogstatsd

Overview

Swift Dogstatsd is a DogStatsD client with three library products:

• DogstatsdCore: the pure NIO-backed client and metric API.
• DogstatsdVapor: Vapor-specific integration on top of the core client.
• Dogstatsd: the backward-compatible compatibility product that re-exports the historical combined surface.

The current package manifest supports Swift 5.9+ and is validated in CI on Swift 5.9 and 6.2.

Installation

Add Swift Dogstatsd with Swift Package Manager:

.package(url: "https://github.com/DataDog/swift-dogstatsd.git", from: "1.0.0"),

Backward-Compatible Vapor Surface

Existing users can keep depending on Dogstatsd and import Dogstatsd:

.target(name: "App", dependencies: [
    .product(name: "Dogstatsd", package: "swift-dogstatsd")
])

Core NIO Client

Use only the core product if you want the DogStatsD client and metric APIs:

.target(name: "App", dependencies: [
    .product(name: "DogstatsdCore", package: "swift-dogstatsd")
])

Vapor Integration

Use the Vapor product if you want Application and Request extensions:

.target(name: "App", dependencies: [
    .product(name: "DogstatsdVapor", package: "swift-dogstatsd")
])

Note: the package is split into separate products, but SwiftPM still resolves package-level dependencies for the repository. In practice that means consumers can choose the Dogstatsd or DogstatsdVapor module they use, but some tools may still fetch the Vapor dependency graph even when only the core product is selected.

Usage

Core NIO Client

The core package works on its own without Vapor:

import DogstatsdCore
import NIOPosix

let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
let client = try NIODogstatsdClient(
    on: eventLoopGroup,
    clientConfig: .udp(address: "127.0.0.1", port: 8125)
)
defer { try? client.shutdown() }

client.increment("custom.swift.metric", tags: ["env:prod"])

For short-lived processes like CLIs or scripts, call client.shutdown() before tearing down the event loop group so queued metrics are flushed and the UDP channel closes cleanly.

Vapor Integration

DogstatsdVapor adds the Vapor-specific extensions:

import DogstatsdVapor

// Called before your application initializes.
func configure(_ app: Application) throws {

    app.dogstatsd.config = .udp(address: "127.0.0.1", port: 8125)
    // or 
    app.dogstatsd.config = .uds(path: "/tmp/dsd.sock")

}

After configuration, dogstatsd is available on both Application and Request:

import Vapor
import DogstatsdVapor

func routes(_ app: Application) throws {
    app.get { req -> String in
        req.dogstatsd.increment("custom.swift.metric", tags: ["env:prod"])
        return "It works!"
    }
}

Testing

Run the core unit test suite from the root package with:

swift test

Vapor integration and backward-compatibility checks live in a separate local package so the root test graph stays Swift-5-friendly and focused on the core package:

swift test --package-path Compatibility/VaporCompatibility

Example Apps

Two executable example apps are included for local verification and contributor onboarding:

• DogstatsdNIOExample: a minimal pure-NIO client that sends a couple of example metrics.
• DogstatsdVaporExample: a Vapor app that wires up app.dogstatsd and emits a metric on each request.

Run them with:

swift run --package-path Examples/DogstatsdNIOExample
swift run --package-path Examples/DogstatsdVaporExample

Both examples default to DOGSTATSD_HOST=127.0.0.1 and DOGSTATSD_PORT=8125.

Devcontainer

This repository includes a VS Code devcontainer in .devcontainer/devcontainer.json.

VS Code workspace helpers are also included in launch.json and tasks.json for:

• building the package
• running the unit tests
• running the Vapor compatibility package
• running the NIO example app
• running the Vapor example app