Custom :: tilegroxy Docs

Description

See Extensibility for details on how custom modules work and their limitations.

Custom scripts run unrestricted and can use the entire standard library including os/exec. Be as cautious using a third party analytics script as you would be executing any other third party software.

Scripts cannot import third party libraries so a destination requiring a vendor SDK needs a native module instead. net/http is available which suffices for most HTTP APIs.

The Script

Your script must be in package custom and define a function named record:

package custom

import (
	"tilegroxy/tilegroxy"
)

func record(ctx tilegroxy.Context, events []tilegroxy.AnalyticsEvent, params map[string]interface{}, msgs tilegroxy.ErrorMessages) error {
	// ...
	return nil
}

The record function is called once per batch of events rather than once per event since interpreting Go carries a per-call overhead. Use batch.maxSize and batch.maxAge to control how often it runs.

Each AnalyticsEvent contains Time, LayerID, LayerName, Z, X, Y, UserID and Fields, the last being a map of whatever you selected via fields and extraFields.

The params argument receives every configuration parameter that isn’t one of the module’s own. Use this to pass a URL, a filename, or credentials to the script. The name parameter is included in this map.

Returning an error causes the batch to be logged as failed and discarded. The error never reaches the user.

Also accepts the batching parameters shared by every analytics module.

Example

YAML
JSON

analytics:
  name: custom
  file: examples/analytics/custom_webhook.go
  url: https://example.com/usage
  fields:
    - duration
  batch:
    maxSize: 100
    maxAge: 60

{
  "analytics": {
    "name": "custom",
    "file": "examples/analytics/custom_webhook.go",
    "url": "https://example.com/usage",
    "fields": [
      "duration"
    ],
    "batch": {
      "maxSize": 100,
      "maxAge": 60
    }
  }
}

A complete working script is available in examples/analytics/custom_webhook.go.

Configuration

Configuration options
Parameter	Description	Type	Required	Default
`File`	An absolute file path to find the Go code implementing the module. Mutually exclusive with Script	string	No	None
`Script`	The Go code implementing the module, supplied inline. Mutually exclusive with File	string	No	None
`ID`	An identifier for this destination, used in logs to attribute analytics messages	string	No	custom
`Fields`	Additional attributes to record. See Analytics	string[]	No	None
`ExtraFields`	Arbitrary additional attributes. See Analytics	map[string]string	No	None
`Any`	Any additional parameter you include will be automatically supplied to your custom module as-is	Any	No	None

One of File or Script is required.