Methods

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.

Outputs:

Name Type Description
id string The alert id.

get_alert

The get_alert method returns an alert.

Inputs:

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

Outputs:

Name Type Description
alert Alert The alert.

get_alerts

The get_alerts method returns all alerts in a project.

Inputs:

Name Type Description
project_id string The project id.

Outputs:

Name Type Description
alerts array of Alert The alerts.

remove_alert

The remove_alert method removes an alert.

Inputs:

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

test_alert

The test_alert method test the alert configuration.

Inputs:

Name Type Description
alert Alert The alert.

update_alert

The update_alert method updates an alert.

Inputs:

Name Type Description
alert Alert The alert.

update_notification

The update_notification method updates a notification.

Inputs:

Name Type Description
notification Notification The notification.

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.
project_id string The project id.

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.
project_id string The project id.
query string The search query string.
start timestamp The start timestamp, events before this time are not included.
stop timestamp The stop timestamp, events after this time are not included.
timeout integer A request timeout in seconds, after which a timeout error is returned.

Outputs:

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

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.
query string The search query string.
start timestamp The start timestamp, events before this time are not included.
stop timestamp The stop timestamp, events after this time are not included.
timeout integer A request timeout in seconds, after which a timeout error is returned.

Outputs:

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

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.
query string The search query string.
start timestamp The start timestamp, events before this time are not included.
stop timestamp The stop timestamp, events after this time are not included.
timeout integer A request timeout in seconds, after which a timeout error is returned.

Outputs:

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

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.
project_id string The project id.
query string The search query string.
start timestamp The start timestamp, events before this time are not included.
stop timestamp The stop timestamp, events after this time are not included.
timeout integer A request timeout in seconds, after which a timeout error is returned.

Outputs:

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

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.
limit integer The maximum number of values to return.
project_id string The project id.
query string The search query string.
start timestamp The start timestamp, events before this time are not included.
stop timestamp The stop timestamp, events after this time are not included.
timeout integer A request timeout in seconds, after which a timeout error is returned.

Outputs:

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

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.
project_id string The project id.
query string The search query string.
start timestamp The start timestamp, events before this time are not included.
stop timestamp The stop timestamp, events after this time are not included.
timeout integer A request timeout in seconds, after which a timeout error is returned.

Outputs:

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

query

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

Inputs:

Name Type Description
project_id string The project id.
query string The SQL query string.
timeout integer A request timeout in seconds, after which a timeout error is returned.

Outputs:

Name Type Description
results array of object The query results.
stats QueryStats The query statistics.

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.
project_id string The project id.
query string The search query string.
start timestamp The start timestamp, events before this time are not included.
stop timestamp The stop timestamp, events after this time are not included.
timeout integer A request timeout in seconds, after which a timeout error is returned.

Outputs:

Name Type Description
results array of object The query results.
stats QueryStats The query statistics.

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.

Outputs:

Name Type Description
id string The notification id.

get_notification

The get_notification method returns a notification.

Inputs:

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

Outputs:

Name Type Description
notification Notification The notification.

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.

Outputs:

Name Type Description
notifications array of Notification The notifications.

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.
project_id string The project id.

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_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.

Outputs:

Name Type Description
id string The project id.

get_project_stats

The get_project_stats method returns project statistics.

Inputs:

Name Type Description
project_id string The project id.

Outputs:

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

get_projects

The get_projects method returns all projects.

Outputs:

Name Type Description
projects array of Project The projects.

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.

update_project

The update_project method updates a project.

Inputs:

Name Type Description
project Project The project.