Types

This section provides details for the type definitions used throughout the API.

Alert

The Alert represents configuration for performing alerting.

Name Type Description
project_id string The associated project id. required
name string The name of the alert. required
severity string The severity of the alert. Must be one of: info, notice, error, critical. required
query string The query performed by the alert. required
operator string The operator used when comparing against the threshold. Must be one of: >, >=, <, <=. required
notification_id string The notification id for reporting alerts, when omitted the alert will not run. required
id string The alert id. read-only
description string The description of the alert.
interval integer The interval in minutes for performing the alert.
muted boolean A boolean used ignore trigger and resolve notifications.
threshold integer The threshold for comparison against the selected operator.
limit integer The maximum number of events in the alert notification.
updated_at timestamp A timestamp indicating when the alert was last updated. read-only
created_at timestamp A timestamp indicating when the alert was created. read-only

Examples

An alert configured to notify the team when one or more errors is found.

{
  "created_at": "2019-11-22T13:48:44.21231Z",
  "description": "All production errors",
  "id": "1RHyOWJ8cIlvDb1bcKZHdiISnX6",
  "interval": 5,
  "limit": 100,
  "muted": false,
  "name": "Errors",
  "notification_id": "1Q3bUUxSUZVlreTTwVzdK5z37iX",
  "operator": ">=",
  "project_id": "ping_production",
  "query": "level > warning or message contains \"panic\"",
  "severity": "error",
  "threshold": 1,
  "updated_at": "2019-11-22T13:48:44.21231Z"
}

BooleanFieldStat

The BooleanFieldStat represents a boolean field’s stats.

Name Type Description
value boolean The boolean value.
count integer The number of times this field occurred in the sampled events.
percent float The percentage of occurrences in the sampled events.

Examples

A total of 95%, or 245 events have the field defined as true.

{
  "count": 245,
  "percent": 0.95,
  "value": true
}

A total of 4%, or 12 events have the field defined as false.

{
  "count": 12,
  "percent": 0.04,
  "value": false
}

DiscoveredField

The DiscoveredField represents a single discovered field.

Name Type Description
name string The field name.
type string The type of discovered field. Must be one of: string, number, boolean.
count integer The number of times this field occurred in the sampled events.
percent float The percentage of occurrences in the sampled events.

Examples

The aws.log.group is a user-defined string field, present in 97% of the events.

{
  "count": 14417,
  "name": "aws.log.group",
  "percent": 0.97,
  "type": "string"
}

The duration field is a user-defined numeric field, present in 11% of the events.

{
  "count": 1770,
  "name": "duration",
  "percent": 0.11,
  "type": "number"
}

The message field is an example of a built-in field, so it is included in 100% of the events.

{
  "count": 14500,
  "name": "message",
  "percent": 1,
  "type": "string"
}

Event

The Event represents a single log event.

Name Type Description
message string The log message. required
level string The severity level. Must be one of: debug, info, notice, warning, error, critical, alert, emergency. required
id string The event id.
fields object The log fields.
timestamp timestamp The creation timestamp.

Examples

An example alert reporting event. This event searchable with message = "reporting complete", or any of the user-defined fields, for example aws.region = "us-west-2".

{
  "fields": {
    "action": "email",
    "action_value": "tj@apex.sh",
    "alert_id": 525,
    "aws": {
      "log": {
        "group": "/aws/lambda/vitals_alert_reporter",
        "stream": "2020/01/14/[59]52bfc9d224d644dc963e3ea1cd7590be"
      },
      "region": "us-west-2"
    },
    "check_id": 21802,
    "function": "alert_reporter",
    "triggered": true,
    "value": 2,
    "version": "59"
  },
  "id": "1WOCGwjnBdxHiD9HEduUAxgVEbC",
  "level": "info",
  "message": "reporting complete",
  "timestamp": "2020-01-14T14:12:26.779999971Z"
}

Notification

The Notification represents an alert notification.

Name Type Description
project_id string The associated project id. required
name string The name of the notification. required
type string The type of notification. Must be one of: slack, pagerduty, email, sms, webhook. required
id string The notification id. read-only
slack_webhook_url string The Slack webhook URL.
slack_channel string The Slack channel name, otherwise the default for the webhook is used.
webhook_url string The webhook URL which receives the alert payloads.
sms_numbers array of string The receipients of the alert notifications.
email_addresses array of string The receipients of the alert notifications.
pagerduty_service_key string The PagerDuty service key.
updated_at timestamp A timestamp indicating when the notification was last updated. read-only
created_at timestamp A timestamp indicating when the notification was created. read-only

Examples

An email notification configured for the backend ops team.

{
  "created_at": "2019-08-28T14:24:02.531785Z",
  "email_addresses": [
    "ops@apex.sh"
  ],
  "id": "1Q3bUUxSUZVlreTTwVzdK5z37iX",
  "name": "Email backend team",
  "project_id": "ping_production",
  "type": "email",
  "updated_at": "2019-08-28T14:24:02.531785Z"
}

Project

The Project represents a customer application.

Name Type Description
name string The human-friendly project name. required
location string The geographical location where the log events are stored. Must be one of: us-west2, northamerica-northeast1, us-east4, southamerica-east1, europe-north1, europe-west2, europe-west6, asia-east2, asia-south1, asia-northeast2, asia-east1, asia-northeast1, asia-southeast1, australia-southeast1. required
id string The project id. read-only
retention integer The retention of log events in days. When zero the logs do not expire.
description string The project description.
updated_at timestamp A timestamp indicating when the project was last updated. read-only
created_at timestamp A timestamp indicating when the project was created. read-only

Examples

A project configured for a production environment with 60 days of log retention.

{
  "created_at": "2019-10-30T11:44:26.005127Z",
  "description": "Apex production logs",
  "id": "apex_production",
  "location": "europe-west2",
  "name": "Apex Production",
  "retention": 60,
  "updated_at": "2019-10-30T11:44:26.005127Z"
}

QueryStats

The QueryStats represents query statistics.

Name Type Description
total_bytes_processed integer The total number of bytes processed by the query.
total_bytes_billed integer The total number of bytes billed by the query.
cache_hit boolean A boolean indicating if the query was cached.
duration integer The query duration in milliseconds.

Examples

An example of query stats.

{
  "cache_hit": false,
  "duration": 2503,
  "total_bytes_billed": 49283072,
  "total_bytes_processed": 48600899
}

Search

The Search represents a saved search query.

Name Type Description
name string The name of the saved search. required
project_id string The associated project id. required
query string The saved search query. required
id string The saved search id. read-only
updated_at timestamp A timestamp indicating when the saved search was last updated. read-only
created_at timestamp A timestamp indicating when the saved search was created. read-only

Examples

An example of a saved search query.

{
  "created_at": "2020-03-30T11:23:37.675798+01:00",
  "id": "1ZqPnX3WN2hAGHjKeQpRfEaLYMr",
  "name": "Weekly reports",
  "project_id": "ping_production",
  "query": "function = \"reporter\"  and message in (\"fetching reports\", \"reporting complete\")",
  "updated_at": "2020-03-30T11:30:54.874927+01:00"
}

StringFieldStat

The StringFieldStat represents a string field’s stats.

Name Type Description
value string The string value.
count integer The number of times this field occurred in the sampled events.
percent float The percentage of occurrences in the sampled events.

Examples

The field’s string value is “downtime” for 87% of the events.

{
  "count": 3413,
  "percent": 0.87,
  "value": "downtime"
}

The field’s string value is “time_total” for 4% of the events.

{
  "count": 168,
  "percent": 0.04,
  "value": "time_total"
}

The field’s string value is “time_namelookup” for 0.1% of the events.

{
  "count": 6,
  "percent": 0.001,
  "value": "time_namelookup"
}

TimeseriesPoint

The TimeseriesPoint represents a single point in a timeseries query.

Name Type Description
timestamp timestamp The bucket timestamp.
count integer The number of events for this bucket.

Examples

A timeseries point with 5 events.

{
  "count": 5,
  "timestamp": "2020-01-15T13:35:38Z"
}

Token

The Token represents an API token.

Name Type Description
scopes array of string Available to this token, permitting access to read and write data. Must be one of: events:read, events:write, alerts:read, alerts:write, notifications:read, notifications:write, projects:read, projects:write, tokens:read, tokens:write, searches:read, searches:write. required
id string The token. read-only
description string The description of the token.
last_used_at timestamp A timestamp indicating when the token was last used. read-only
created_at timestamp A timestamp indicating when the token was created. read-only