Methods

This section provides details for the method calls available in the API, grouped by topic.

Alerts

Alerts define the queries and thresholds used to notify your team of errors and anomalies.

Method Description
add_alert Creates a new alert.
get_alert Returns an alert.
get_alerts Returns all alerts in a project.
remove_alert Removes an alert.
test_alert Test the alert configuration.
update_alert Updates an alert.
update_notification Updates a notification.

add_alert

The add_alert method creates a new alert.

Inputs:

Name Type Description
alert Alert The alert. required

Outputs:

Name Type Description
id string The alert id. required

get_alert

The get_alert method returns an alert.

Inputs:

Name Type Description
alert_id string The alert id. required
project_id string The project id. required

Outputs:

Name Type Description
alert Alert The alert. required

get_alerts

The get_alerts method returns all alerts in a project.

Inputs:

Name Type Description
project_id string The project id. required

Outputs:

Name Type Description
alerts array of Alert The alerts. required

remove_alert

The remove_alert method removes an alert.

Inputs:

Name Type Description
alert_id string The alert id. required
project_id string The project id. required

test_alert

The test_alert method test the alert configuration.

Inputs:

Name Type Description
alert Alert The alert. required

update_alert

The update_alert method updates an alert.

Inputs:

Name Type Description
alert Alert The alert. required

update_notification

The update_notification method updates a notification.

Inputs:

Name Type Description
notification Notification The notification. required

Events

Events represent the log events ingested by one or more programs in your project.

Method Description
add_events Ingests a batch of events.
get_boolean_field_stats Returns field statistics for a boolean field.
get_count Performs a search query against the log events, returning the number of matches.
get_discovered_fields Returns fields discovered in the provided time range.
get_numeric_field_stats Returns field statistics for a numeric field.
get_string_field_stats Returns field statistics for a string field.
get_timeseries Returns a timeseries of event counts in the provided time range.
query Performs a SQL query against the log events.
search Performs a search query against the log events.

add_events

The add_events method ingests a batch of events.

Inputs:

Name Type Description
events array of Event The batch of events. required
project_id string The project id. required

get_boolean_field_stats

The get_boolean_field_stats method returns field statistics for a boolean field.

Inputs:

Name Type Description
field string The field name. required
project_id string The project id. required
query string The search query string.
start timestamp The start timestamp, events before this time are not included. required
stop timestamp The stop timestamp, events after this time are not included. required

Outputs:

Name Type Description
stats QueryStats The query statistics. required
values array of BooleanFieldStat The boolean values. required

get_count

The get_count method performs a search query against the log events, returning the number of matches.

Inputs:

Name Type Description
project_id string The project id. required
query string The search query string.
start timestamp The start timestamp, events before this time are not included. required
stop timestamp The stop timestamp, events after this time are not included. required

Outputs:

Name Type Description
count integer The query result count. required
stats QueryStats The query statistics. required

get_discovered_fields

The get_discovered_fields method returns fields discovered in the provided time range.

Inputs:

Name Type Description
project_id string The project id. required
query string The search query string.
start timestamp The start timestamp, events before this time are not included. required
stop timestamp The stop timestamp, events after this time are not included. required

Outputs:

Name Type Description
fields array of DiscoveredField The fields discovered. required
stats QueryStats The query statistics. required

get_numeric_field_stats

The get_numeric_field_stats method returns field statistics for a numeric field.

Inputs:

Name Type Description
field string The field name. required
project_id string The project id. required
query string The search query string.
start timestamp The start timestamp, events before this time are not included. required
stop timestamp The stop timestamp, events after this time are not included. required

Outputs:

Name Type Description
avg float The avg value. required
max float The max value. required
min float The min value. required
stats QueryStats The query statistics. required

get_string_field_stats

The get_string_field_stats method returns field statistics for a string field.

Inputs:

Name Type Description
field string The field name. required
limit integer The maximum number of values to return.
project_id string The project id. required
query string The search query string.
start timestamp The start timestamp, events before this time are not included. required
stop timestamp The stop timestamp, events after this time are not included. required

Outputs:

Name Type Description
stats QueryStats The query statistics. required
values array of StringFieldStat The string values. required

get_timeseries

The get_timeseries method returns a timeseries of event counts in the provided time range.

Inputs:

Name Type Description
max_points integer The maxmimum number of datapoints to return. required
project_id string The project id. required
query string The search query string.
start timestamp The start timestamp, events before this time are not included. required
stop timestamp The stop timestamp, events after this time are not included. required

Outputs:

Name Type Description
points array of TimeseriesPoint The series. required
stats QueryStats The query statistics. required

search

The search method performs a search query against the log events.

Inputs:

Name Type Description
limit integer The maxmimum number of events to return.
order string The query timestamp sort order. Must be one of: ascending, descending.
project_id string The project id. required
query string The search query string.
start timestamp The start timestamp, events before this time are not included. required
stop timestamp The stop timestamp, events after this time are not included. required

Outputs:

Name Type Description
events array of Event The query search results. required
stats QueryStats The query statistics. required

Example

Input:

{
  "limit": 500,
  "project_id": "app_production",
  "query": "function = \"alert_reporter\" and message = \"reporting complete\"",
  "start": "2020-01-14T13:56:05.961Z",
  "stop": "2020-01-15T13:56:05.961Z"
}

Output:

{
  "results": [
    {
      "fields": "{\"action\":\"slack\",\"alert_id\":3637,\"aws\":{\"log\":{\"group\":\"/aws/lambda/vitals_alert_reporter\",\"stream\":\"2020/01/15/[61]6865a073c8864f1f820ba002c0cea12e\"},\"region\":\"us-west-2\"},\"check_id\":17142,\"function\":\"alert_reporter\",\"triggered\":true,\"value\":1,\"version\":\"61\"}",
      "id": "1WQyis5UQYQeIYMFAbNjkvKLjsn",
      "level": "info",
      "message": "reporting complete",
      "timestamp": "2020-01-15T13:50:26.628999948Z"
    },
    {
      "fields": "{\"action\":\"slack\",\"alert_id\":5322,\"aws\":{\"log\":{\"group\":\"/aws/lambda/vitals_alert_reporter\",\"stream\":\"2020/01/15/[61]6865a073c8864f1f820ba002c0cea12e\"},\"region\":\"us-west-2\"},\"check_id\":21055,\"function\":\"alert_reporter\",\"triggered\":true,\"value\":5,\"version\":\"61\"}",
      "id": "1WQxxVw35oaoCcfCXGYj9jx1zmn",
      "level": "info",
      "message": "reporting complete",
      "timestamp": "2020-01-15T13:44:10.963000059Z"
    }
  ],
  "stats": {
    "cache_hit": false,
    "total_bytes_billed": 1493172224,
    "total_bytes_processed": 1492717808
  }
}

Notifications

Notifications define how alerts are delivered to your team, such as email, Slack, SMS, PagerDuty or Webhook.

Method Description
add_notification Creates a new notification.
get_notification Returns a notification.
get_notifications Returns all notifications.
remove_notification Removes a notification.

add_notification

The add_notification method creates a new notification.

Inputs:

Name Type Description
notification Notification The notification. required

Outputs:

Name Type Description
id string The notification id. required

get_notification

The get_notification method returns a notification.

Inputs:

Name Type Description
notification_id string The notification id. required
project_id string The project id. required

Outputs:

Name Type Description
notification Notification The notification. required

Example

Input:

{
  "notification_id": "1Q3bUUxSUZVlreTTwVzdK5z37iX",
  "project_id": "ping_production"
}

Output:

{
  "notification": {
    "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"
  }
}

get_notifications

The get_notifications method returns all notifications.

Inputs:

Name Type Description
project_id string The project id. required

Outputs:

Name Type Description
notifications array of Notification The notifications. required

Example

Input:

{
  "project_id": "ping_production"
}

Output:

{
  "notifications": [
    {
      "created_at": "2019-08-28T14:24:02.531785Z",
      "email_addresses": [
        "tj@apex.sh"
      ],
      "id": "1Q3bUUxSUZVlreTTwVzdK5z37iX",
      "name": "Email backend team",
      "project_id": "ping_production",
      "type": "email",
      "updated_at": "2019-08-28T14:24:02.531785Z"
    },
    {
      "created_at": "0001-01-01T00:00:00Z",
      "id": "1RhHf76rlKzNQ25fPhRlI0Qfvf8",
      "name": "Send Slack message",
      "project_id": "ping_production",
      "slack_channel": "#alerts",
      "slack_webhook_url": "https://hooks.slack.com/services/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",
      "type": "slack",
      "updated_at": "2019-12-12T13:01:10.751508Z"
    }
  ]
}

remove_notification

The remove_notification method removes a notification.

Inputs:

Name Type Description
notification_id string The notification id. required
project_id string The project id. required

Projects

A project is a distinct set of events, alerts, and notifications. You may create separate projects for various projects, or to separate by environment such as production and staging.

Method Description
add_project Creates a new project.
get_instance_config Returns instance configuration.
get_project_stats Returns project statistics.
get_projects Returns all projects.
remove_project Removes a project.
update_project Updates a project.

add_project

The add_project method creates a new project.

Inputs:

Name Type Description
project Project The project. required

Outputs:

Name Type Description
id string The project id. required

get_project_stats

The get_project_stats method returns project statistics.

Inputs:

Name Type Description
project_id string The project id. required

Outputs:

Name Type Description
bytes_total integer The total number of bytes stored. required
events_total integer The total number of events stored. required

get_projects

The get_projects method returns all projects.

Outputs:

Name Type Description
projects array of Project The projects. required

Example

Input:

None.

Output:

{
  "projects": [
    {
      "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"
    },
    {
      "created_at": "2019-11-28T12:33:00.034366Z",
      "description": "Ping production logs.",
      "id": "ping_production",
      "location": "europe-west2",
      "name": "Ping Production",
      "retention": 60,
      "updated_at": "2019-11-28T12:33:00.034366Z"
    },
    {
      "created_at": "2019-11-28T12:34:38.58472Z",
      "description": "Test project logs.",
      "id": "testing",
      "location": "europe-west2",
      "name": "Testing",
      "retention": 15,
      "updated_at": "2019-11-28T12:34:38.58472Z"
    }
  ]
}

remove_project

The remove_project method removes a project.

Inputs:

Name Type Description
project_id string The project id. required

update_project

The update_project method updates a project.

Inputs:

Name Type Description
project Project The project. required

Search

Saved searches provide quick team-wide access to common search queries.

Method Description
add_search Creates a new saved search.
get_searches Returns all saved searches in a project.
remove_search Removes a saved search.
update_search Updates a saved search.

add_search

The add_search method creates a new saved search.

Inputs:

Name Type Description
search Search The saved search. required

Outputs:

Name Type Description
id string The saved search id. required

Example

An example of a saved search query for reporting related messages.

Input:

{
  "name": "Weekly reports",
  "project_id": "ping_production",
  "query": "function = \"reporter\" and message in (\"fetching reports\", \"reporting complete\")"
}

Output:

{
  "id": "1ZqPnuhRyStpljCI8ahVSsV9txx"
}

get_searches

The get_searches method returns all saved searches in a project.

Inputs:

Name Type Description
project_id string The project id. required

Outputs:

Name Type Description
searches array of Search The saved searches.

Example

An example listing all of the saved searches for a project.

Input:

{
  "project_id": "ping_production"
}

Output:

{
  "searches": [
    {
      "created_at": "2020-03-30T11:23:16.099557+01:00",
      "id": "1ZqPkpH63A5ZpOJEX443ZirtmH6",
      "name": "Alert notifications",
      "project_id": "ping_production",
      "query": "function = \"alert_reporter\" and message = \"reporting complete\"",
      "updated_at": "2020-03-30T11:24:39.560604+01:00"
    },
    {
      "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:23:54.874927+01:00"
    },
    {
      "created_at": "2020-03-30T11:23:40.364422+01:00",
      "id": "1ZqPnuhRyStpljCI8ahVSsV9txx",
      "name": "Lambda timeouts",
      "project_id": "ping_production",
      "query": "message contains \"timed out\"",
      "updated_at": "2020-03-30T11:23:45.569638+01:00"
    }
  ]
}

remove_search

The remove_search method removes a saved search.

Inputs:

Name Type Description
project_id string The project id. required
search_id string The saved search id. required

update_search

The update_search method updates a saved search.

Inputs:

Name Type Description
search Search The saved search. required

Tokens

API tokens act much like a password, providing access to perform requests to all or a subset of methods based on the scopes permitted.

Method Description
add_token Creates a new token.
get_tokens Returns all tokens.
remove_token Removes a token.

add_token

The add_token method creates a new token.

Inputs:

Name Type Description
token Token The token. required

Outputs:

Name Type Description
id string The token id.

get_tokens

The get_tokens method returns all tokens.

Outputs:

Name Type Description
tokens array of Token The tokens.

remove_token

The remove_token method removes a token.

Inputs:

Name Type Description
token_id string The token id. required