Overview of Understand.io Features

• Introduction
• How to Send Data
• Sending Errors via the API
• How to Search

Introduction

Understand.io is a real-time centralized event, log data management and analytics service. It allows you to search, filter and group data by your defined queries and makes it possible to find answers to very complex questions about your event data.

How to Send Data

The Understand.io API is based on the HTTP protocol which is well supported in most programming languages.

One of the simplest examples on how to send events is via CURL:

curl -XPOST https://api.understand.io/your-input-key -d '{"message":"my very first event"}'

• your-input-key is an API key from your channel administration tab and is unique for each channel.
• {"message":"my very first event"} is the JSON event that you would like to send.

Events sent this way appear in Search. To make an event show up in the Errors view, see Sending Errors via the API.

Sending Errors via the API

Error events appear in the Errors view, where all events with the same group_id are grouped together as occurrences of one error.

• If you send an event with "level": "error" (or critical, alert, emergency, fatal) and a class or stack, a group_id is generated for you from its class, file and line.
• You can set your own group_id to control grouping. Any string works, for example "checkout-failed". A 40-character value, such as a SHA-1 hash, is stored as is.
• Plain log events without an error level and exception data are stored and searchable in Search, but are not grouped as errors.

timestamp is optional and accepts seconds or milliseconds since the epoch (integer or decimal) or an ISO 8601 date string. Sensitive data is masked on arrival, before it is stored:

• Payment card numbers are masked down to their last 4 digits.
• Values of sensitive fields such as password, token, authorization, cvv and card_number are replaced with [value hidden].

Example:

curl -XPOST https://api.understand.io/your-input-key \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "invalid literal for int() with base 10",
    "level": "error",
    "class": "ValueError",
    "file": "app/services/orders.py",
    "line": 63
  }'

The official SDKs (Laravel, JavaScript and Python) set group_id for you when you report an exception.

Related Resources

• How to setup the Laravel service provider

How to Search

Understand.io supports simple and advanced search queries to make searching useful in all situations.

You can start executing search queries once you have a few events in your channel. In the following example we have sent three events to our channel:

{"message":"my first event"}
{"message":"my second event"}
{"message":"my third event"}

Notice that we have same term my in all three events. This means that if we search just for this word, we will see all 3 events.

To make life easier, Understand.io also supports filters where you can filter out results by specific properties, values and conditions.

In the following example we specify that the property message must contain the term "first".

These are just a few simple examples on how to get started with search. For more information please see the Advanced Guide on How to Search.