lua-resty-ga

Send nginx/openresty access log to Google Analytics.

Status

This library is used in PoweredBy.Cloud, but you should test it in your system before onboarding.

Requires

ledgetech/lua-resty-http >= 0.14

Install

luarocks install lua-resty-ga

opm get BeanYoung/lua-resty-ga

Usage

# ga.conf

resolver 8.8.8.8 223.5.5.5 valid=3600s ipv6=off;

lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;

lua_shared_dict ga_cache 128m;

init_by_lua_block {
    local process = require 'ngx.process'
    process.enable_privileged_agent()
}

init_worker_by_lua_block {
    local process = require 'ngx.process'
    local ga = require 'resty.ga'

    if process.type() == 'privileged agent' then
        ngx.timer.every(1, ga.send)
    end
}

server {
    listen 0.0.0.0:80;
    location / {
        content_by_lua_block {
            ngx.say('ok')
        }

        log_by_lua_block {
            local ga = require 'resty.ga'

            -- Follow this link to create your tid.
            -- https://support.google.com/analytics/answer/10269537
            local tid = 'UA-188032216-1'

            -- Get cid from cookie or somewhere else based on your implementation
            local cid = 'user_id_0'

            local uip = ngx.var.remote_addr
            -- if your nginx is behind cloudflare
            local headers = ngx.req.get_headers()
            if headers['CF-Connecting-IP'] then
                uip = headers['CF-Connecting-IP']
            end

            ga.collect(tid, cid, uip)

            -- Follow this link to create custom dimensions and custom metrics.
            -- https://support.google.com/analytics/answer/2709829?hl=en
            -- Then you can send custom dimensions and custom metrics like this.
            --ga.collect(tid, cid, uip, true)
        }
    }
}

Methods

collect

syntax: ga.collect(tid, cid, uip, send_cd_and_cm)

Collect current request's log and push to cache. It's better to call this method during log phaselog_by_lua_*.

tid is your google analytics tracking id. Please be aware that this is a Universal Analytics property rather than a Google Analytics 4 property. Follow this link to create a tracking id.

cid is google analytics client id.

uip is google analytics client ip address.

send_cd_and_cm is used to deside whether to send custom dimensions and custom metrics to google analytics. Custom dimensions and custom metrics must be created in google analytics's admin dashboard before setting this parameter to true. Also custom dimensions and custom metrics must be created in the following order:

Custom Dimensions	Index	Scope
Status Code	1	HIT
Content Type	2	HIT
Cache Status	3	HIT
Http Method	4	HIT

Custom Metrics	Index	Scope	Format Type
Content Length	1	HIT	Integer
Response Time	2	HIT	Integer

send

syntax: ga.send(premature)

Pop all request logs and send to google analytics server. It's better to use timer to call this method in privileged agent every 1s.

Author

Bingyu Chen BeanYoung.

beanyoung / lua-resty-ga