Skip to content

Library to connect nginx lua script to Datadog/statsd logging


Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit



17 Commits

Repository files navigation

Ngx Lua Datadog connecter

Simple libary extracted from the Kong project that allows for Datadog(statsd) collection from inside lua scripts running in nginx


Include the library code in your nginx configuration, usually inside the http block but outside the server block

# set path for lua libraries - ;; means append existing paths
lua_package_path "/path/to/ngx_lua_datadog/lib/?.lua;;";

use in a location stanza:

local conf = { host = "", port = 8125, namespace = "Lua_Stats_App", timeout = 1}
local statsd_logger = require "ngx_lua_datadog"
local logger, err = statsd_logger:new(conf)

if err then
     ngx_log(ngx.ERR, "failed to create Statsd logger: ", err)

if ( my_condition ) then
     logger:counter("condition_matched", 1, 1)
     logger:counter("condition_not_matched", 1, 1)

Configuration options

name value
host the ip or name of your statsd server
port the port number your statsd server runs on, default is 8125
timeout the number of seconds for lua to wait to make the connection
namespace the string that all stat messages will be prefixed with

Statistic Gathering

-- Simple counter 
counter(stat, value, sample_rate, tags)

-- Gauge
gauge(stat, value, sample_rate, tags)

-- Timer
timer(stat, ms, tags)

-- Histogram
histogram(stat, value, tags)

-- Meter
meter(stat, value, tags)

-- Sets
set(stat, value, tags)

-- Distribution
distribution(stat, value, tags)

Sample rates are your responsiblity to calculate. If you tell it the sample rate is 0.10 (10 percent), then the value you send needs to be the sampled value. e.g. If you've had 100 hits and you send a 0.20 sample rate, the value you send would be 20

Tag Format

Tags are sent as comma separated key value pairs with a colon deliminating the key from the value, e.g.

tags = "country:china,datacenter:asia,account:mass_market"

logger:counter("another_hit", 1, 1, tags)

Luarock creation

  1. Run sh scripts/ <version> where version corresponds to the tag you want to build. Ex. sh scripts/ v0.1.0.
  2. Upload the .src.rock file to the server (TBD)