1

Deploy Trench

The only prerequisite for Trench is a system that has Docker and Docker Compose installed see installation guide. We recommend having at least 4GB of RAM and 4 CPU cores for optimal performance if you’re running a production environment.

After installing Docker, you can start the local development server by running the following commands:

git clone https://github.com/frigadehq/trench.git
cd trench/apps/trench
cp .env.example .env
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build --force-recreate --renew-anon-volumes

The above command will start the Trench server that includes a local ClickHouse and Kafka instance on http://localhost:4000. You can update the .env to change any of the configuration options.

2

Send a sample event

You can find and update the default public and private API key in the .env file. Using your public API key, you can send a sample event to Trench as such:

curl -i -X POST \
   -H "Authorization: Bearer public-d613be4e-di03-4b02-9058-70aa4j04ff28" \
   -H "Content-Type: application/json" \
   -d \
'{
  "events": [
    {
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "type": "track",
      "event": "ConnectedAccount",
      "properties": {
        "totalAccounts": 4,
        "country": "Denmark"
      }
    }]
}' \
 'http://localhost:4000/events'
3

Quering events

You can query events using the /events endpoint (see API reference for more details).

You can also query events directly from your local Trench server. For example, to query events of type ConnectedAccount, you can use the following URL:

curl -i -X GET \
   -H "Authorization: Bearer private-d613be4e-di03-4b02-9058-70aa4j04ff28" \
   'http://localhost:4000/events?event=ConnectedAccount'

This will return a JSON response with the event that was just sent:

{
  "results": [
    {
      "uuid": "25f7c712-dd86-4db0-89a8-d07d11b73e57",
      "type": "track",
      "event": "ConnectedAccount",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "properties": {
        "totalAccounts": 4,
        "country": "Denmark"
      },
      "timestamp": "2024-10-22T19:34:56.000Z",
      "parsedAt": "2024-10-22T19:34:59.530Z"
    }
  ],
  "limit": 1000,
  "offset": 0,
  "total": 1
}
4

Execute raw SQL queries

Use the queries endpoint to analyze your data. Example:

curl -i -X POST \
   -H "Authorization: Bearer private-d613be4e-di03-4b02-9058-70aa4j04ff28" \
   -H "Content-Type: application/json" \
   -d \
'{
  "queries": [
    "SELECT COUNT(*) FROM events WHERE userId = '550e8400-e29b-41d4-a716-446655440000'"
  ]
}' \
 'http://localhost:4000/queries'

Sample query result:

{
  "results": [
    {
      "count": 5
    }
  ],
  "limit": 0,
  "offset": 0,
  "total": 1
}

​
Going Further

While the above steps are a great starting point, the following video tutorial exemplifies the many things you can do with Trench. In this video, we build a mini version of Google Analytics using Trench and Grafana:

JavaScript Client →

Get Events API →

Create Events API →

Webhooks API →