1. Home
  2. Docs
  3. Modeling your data
  4. Handling Alerts via Snowplow Insights

Handling Alerts via Snowplow Insights


If you are a Snowplow Insights customer, you have full control over your data model – including receiving alerts and handling job failures. Jobs can be paused, and alerts and locks configured via the configuration file.


Below is a quick summary of the relevant configuration details for alerts and failures. Full details on configuring data model jobs can be found in the documentation on configuring data model jobs.

Receiving Alerts

To recieve alerts, the data model configuration file must have at least one owners entry, with a name and a valid email address.

"owners": [{ "name": "Bob Foo", "email": "bob@foo.com" }],
Code language: JavaScript (javascript)

Hard and Soft Locks

Locks determine what happens when a job is currently running, and when a job fails.

Both hard and soft locks prevent a job from starting if the same job is already running. Hard locks remain in place if the job fails – and so prevent the next run of the job from starting. Soft locks are removed when a job fails, and so a failed job will be retried on the next scheduled run.

If a hard lock is in place, the job can not be restarted until the lock is removed manually by the Snowplow support team – this can be requested by emailing support@snowplowanalytics.com.

Unless the data model is not safe to restart, we recommend using soft locks. Any standard use of the Snowplow v1 data models are safe to restart, and so can use soft locks. This allows you to resolve any issues that occur in your model without needing to wait for any manual action.

"lockType": "soft",
Code language: JavaScript (javascript)

Pausing a job

If a job fails when configured with a soft lock, it will continue to run on schedule, and will continue to send alerts each time it fails. There’s nothing wrong with letting this happen, however we can also pause the job until we have fixed an issue and are ready to retry the job. This is done by setting enabled to false.

"enabled": false,
Code language: JavaScript (javascript)

Once an issue is resolved, simply set it back to true and the job will run again on schedule.

Dealing with alerts

Once at least one valid owner email address is provided in the config, email alerts will be sent when a data modeling job fails. A data model will fail if there is an error in the SQL itself, an error in running the SQL, or some network connection problem.

Diagnose the failure

The alert itself will normally contain a link to the failed job in the Snowplow Insights Console Jobs tab. This will contain the details of the failed run, including the successful steps.

Under ‘Job Dag’ for the failed job, click on the failed step to see details of what went wrong.

The ‘Error Output’ will show you the error logs from the SQL-runner job. These logs will contain information that the database relayed back to SQL-runner about the failure.

Decide how to handle the issue

In some cases, no action is required to handle the issue. Occasionally there will be some ‘connection refused’ related message, or, for example an EOF error. These are normally simply down to some external database process, or a network connection error.

For these kinds of error no action is required, and the job should succeed on the next run. If it doesn’t, or you need the job to run sooner, reply to the alert email or email support@snowplowanalytics.com directly, to open a support ticket.

If the error output shows some SQL or Syntax error, then the issue is with the model’s SQL. If resolving this error may take some time, you can pause the job using the configuration, as described above. Once you have a fix ready, commit it to the model and unpause the job.

In these cases, we recommend testing the fix by running the SQL locally (using either SQL-runner or some other tool to connect to the database).

If you require the fix to be run before the next scheduled run, you can open a support ticket to kick off a manual run.

If you are unsure or need help

The support team is here to help with anything that’s confusing. Simply reply to the alert email, or email support@snowplowanalytics.com with any questions you have.

If you’d like to learn more about Snowplow Insights you can book a demo with our team, or if you’d prefer, you can try Snowplow technology for yourself quickly and easily.