Friday, April 2, 2021

Show HN: Engauge – Self-hosted, Single-binary Analytics

Engauge

Concept

It's not pretty but it's functional.

Track user interactions in your apps and products in real-time and see the corresponding stats in a simple dashboard.

Allows for custom instrumentation of applications/products by utilizing a simple and consistent data format.

type Interaction struct {
        // how
        Action *string

        // what
        EntityType *string
        EntityID   *string

        // where
        OriginType *string
        OriginID   *string

        // who
        UserType *string
        UserID   *string

        DeviceType *string
        DeviceID   *string

        // why
        SessionType *string
        SessionID   *string

        // when
        Timestamp  *string

        // metadata
        Properties map[string]interface{} `json:"properties,omitempty"`
}

The only required fields are action and userID. All other fields are optional to be sent in an interaction.

A basic example can be found a little further down in this README.

Features

Automatic Session Detection
All-Time Statistics
Interval-Based Statistics
- Hourly
- Daily
- Weekly
- Monthly
- Quarterly
- Yearly
Unit Metrics

build from source

Only a build-from-source option will be made available in the open-source version of Engauge. It's still really simple!

Use make build for a linux binary build. The binary (named engauge) will be placed in a created bin/ directory inside the repository root directory.

The binary is completely self-contained.

self-host

Deploying the engauge service is super simple.

Make sure a domain (or subdomain) e.g,. example.com or sub.example.com are pointed at the VPS instance that you will be deploying Engauge on.

Then, just copy the binary to your favorite VPS instance, set your environment variable values in the start command and start it up (likely using nohup, screen, or systemd).

The start command should look something like this:

ENGAUGE_HTTPS=true ENGAUGE_BASEPATH=engauge-data ENGAUGE_USER=admin ENGAUGE_PASSWORD=my-super-secret-admin-p@$$WorD! ENGAUGE_JWT=jwt-secret-key ENGAUGE_APIKEY=my-secret-api-key ./engauge

You can use make windows for windows binary builds.

Engauge does output logs if you would like to capture those using a logging daemon (but this is completely optional).

It also comes with a health-check endpoint /health that will return a simple alive string value if you want to monitor it externally.

environment variables

ENGAUGE_HTTPS can be used to specify if Engauge should use HTTPS (RECOMMENDED to be set to true, defaults to false)
ENGAUGE_BASEPATH is used to specify the name of the root directory in the local filesystem to store data.
ENGAUGE_TIMEZONE specifies the default timezone for Engauge, defaults to the local timezone of the Engauge service instance.
ENGAUGE_SESSIONDELAY specifies, in minutes, how long to wait after the last seen interaction for a user before considering that user's session to be completed.
ENGAUGE_USER is the admin username
ENGAUGE_PASSWORD is the admin password
ENGAUGE_JWT is the JWT secret key
ENGAUGE_APIKEY is the API key for sending interactions to the Engauge service

Special Values

actions:
- conversions will be counted towards conversion counts, and will be searched for an amount property key for unit metric analytics
Property Keys:
- amount key, expected to be a numerical value

Please note: that all property values must be either: a string (text), a number, a number array, or a string array.

Sending Interactions

After you have found the locations within your app or product that you would like to gather data from (we call these "Endpoints"), you will simply need to send the data via HTTP/JSON.

Just send a POST to the /api/interaction route with your json-encoded interaction object in the request body (and your api key in the api-key header).

Easy as pie.

For example:

curl --location --request POST 'https://example.com/api/interaction' \
--header 'api-key: my-api-key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": "close",
    "entityType": "list",
    "entityID": "list-2",
    "originType": "page",
    "originID": "page-2",
    "userType": "customer",
    "userID": "c9449105-9b01-4385-aab5-b45ce4948b96",
    "deviceType": "desktop-web",
    "deviceID": "d396bded-70a6-46ac-bff6-7e09394c43e0",
    "properties": {
        "browser": "safari",
        "browserVersion": "0.8.6",
        "country": "germany",
        "language": "it",
        "mobile": "false",
        "os": "macos",
        "path": "/page-2",
        "ref": "ddg",
        "screenHeight": 200,
        "screenWidth": 600,
        "userAgent": "b0a63af7-4431-4355-9143-cd75c5a6852a"
    }
}'

POST /api/interaction HTTP/1.1
Host: example.com
api-key: my-api-key
Content-Type: application/json
Content-Length: 686

{
    "action": "close",
    "entityType": "list",
    "entityID": "list-2",
    "originType": "page",
    "originID": "page-2",
    "userType": "customer",
    "userID": "c9449105-9b01-4385-aab5-b45ce4948b96",
    "deviceType": "desktop-web",
    "deviceID": "d396bded-70a6-46ac-bff6-7e09394c43e0",
    "properties": {
        "browser": "safari",
        "browserVersion": "0.8.6",
        "country": "germany",
        "language": "it",
        "mobile": "false",
        "os": "macos",
        "path": "/page-2",
        "ref": "ddg",
        "screenHeight": 200,
        "screenWidth": 600,
        "userAgent": "b0a63af7-4431-4355-9143-cd75c5a6852a"
    }
}

where you will need to replace example.com with your Engauge instance domain.

Roadmap

Many more features for Engauge are currently in progress and/or in planning.

Stay Tuned!

Open-source, not open-contribution

We apologize for having to do this, but Engauge is closed to code contributions (at this time). This keeps the code base free of proprietary or licensed code.

The Engauge team is too small to be accepting and maintaining third party patches for now. Small contributions typically require hours of time to properly test and validate.

However, we are tremendously grateful to the community for any feature requests, ideas, discussions, bug reports, and general involvement!

from Hacker News https://ift.tt/3dvVPro

SymmetricalDataSecurity