Events API

The inbound Events API provides an endpoint where you can send events from monitoring tools such as New Relic, Dynatrace, and Datadog. Moogsoft can ingest from any external tool that can publish event data in JSON format.

The Events API supports the following workflows:

  • Posting: Set up a simple script that regularly posts events to the REST endpoint.

  • Webhook: Set up the REST Integration as an endpoint for a webhook from an external tool.

To send events of interest to Moogsoft, go to Data Config > Integrations > Events API. This page includes a full description of the metric schema and required fields; it also includes auto-generated cURL commands with example JSON events.

The event schema is highly flexible and generic, with a small number of required fields, a larger number of optional fields, and a tag field for ingesting custom data not included in the default schema.

For a description of how Moogsoft deduplicates events and adds them to alerts, see Event deduplication: how-to and best practices.

Before you begin

Before you set up your integration, note the following:

  • Make sure that the event data you send to Moogsoft includes all data fields required by the schema, as well as any additional fields necessary to cluster alerts intelligently and create incidents that meet the needs of your users.

    If your raw data doesn't include all the data you need, map the missing fields to a value like "incomplete event" to handle these events separately.

  • All times must be specified as UNIX time values normalized to Coordinated Universal Time (UTC).

  • Moogsoft stores all times in UTC format. The dates and times displayed in the UI are based on your browser's local time.

  • Make sure that any subsequent updates to an event are consistently populated.

  • Review Moogsoft APIs, which describes the expected request format.

Set up an events integration

To set up an event integration, you configure the external tool to publish to the Events API endpoint of your Moogsoft instance. The general workflow is the same regardless of the tool:

  1. Go to the Moogsoft web UI > Data Config > Integrations > Events API and determine the data fields that you want to ingest.

  2. In the external tool, do the following:

    1. Determine the event types that you want to send to Moogsoft.

    2. Set up the tool to trigger alerts for the infrastructure issues of interest.

    3. Set up the tool to send events to the Events API endpoint in the required format.

Event field reference

Table 2. Events API field reference

Field

Description

Type

source

REQUIRED

The server, node, or other entity that generated the event. This can be any unique, human-readable name such as a hostname, fully qualified domain name, or URL. 

In some cases, a process or application might trigger an event that has no node identification. In this case, specify a unique identifier of the generating instance such as a database name, container name, or cluster node name.

string

description

REQUIRED

A human-readable description of the event. A good description summarizes the exact conditions and thresholds that triggered the event. Examples include:

  • "en0 bandwidth util > 50%"

  • "myApp response time > 1sec"

  • "myWebService 4xx https responses/sec > 20%"

  • "myService unavailable"

When Moogsoft creates or updates an alert with a new event, this description becomes the alert description.

string

severity

REQUIRED

The relative severity of the event. When you define severity levels, consider the significance of an event source if possible. A low-priority source might trigger "high-severity" events that might actually be lower-priority in the context of all your event sources.

Specify an integer or string as follows:

  • 0 — "Clear"

  • 1 — "Unknown" — Avoid this if possible, unless you need to send the specific event and you cannot determine its severity.

  • 2 — "Warning"

  • 3 — "Minor"

  • 4 — "Major"

  • 5 — "Critical"

When Moogsoft creates or updates an alert with a new event, this severity becomes the alert severity.

Integer or string

service

REQUIRED

One or more applications or services that either generated the event or are associated with it. Moogsoft uses the "source", "service", and "check" fields to filter out duplicates and aggregate similar events into alerts.

You can use this tag to specify the level of event aggregation and deduplication in your alerts. For more general alerts, use general names such as "docker" or "ticket-reservation-app". For more targeted alerts, use a microservice or other specific name.

JSON array

check

REQUIRED

The performance, health, or other check that triggered the event. Examples include "cpu load", "mongoDB query", and "web server response code".

If two events involve different problems on the same source and service, they should belong to different alerts. For this reason, the check field should be fairly specific. Suppose two events describe database errors on the same source : one is a replication error and another is a query error. If check = “database” for both events, they will get deduplicated into the same alert. The better choice is to use “database-replication” for the first check and “database-query” for the second.

See Event deduplication: how-to and best practices.

string

class

The high-level classification of the event. Examples include Application, Storage, Network, Operating System, Middleware, Hardware, Virtualization, Serverless, Database, Cloud, and API.

This field determines the class field in the resulting alert. Alert classes can be useful for correlating alerts into incidents. See Correlate Alerts into Incidents.

string

time

Event time in UTC format. You can specify the time in either seconds or milliseconds. If the payload does not include a time, Moogsoft uses the event arrival time.

integer

utc_offset

The difference in hours from Coordinated Universal Time (UTC) for the event time. If you have event sources in different time zones, make sure that the utc_offset is specified to ensure that all event times are based on the same context. Use the following format:

  • GTM+9:30 — UTC plus 9 hours 30 minutes

  • GTM-2:00 — UTC minus 2 hours

string

manager

A general identifier of the event generator or intermediary, such as AppDynamics, NewRelic, Nagios, Docker, RedHat, Mongo, or CloudWatchEC2.

string

manager id

ID for the external manager or tool that sent the alert. This field can be useful with external monitoring tools that support workflow automation: when a user closes an alert in Moogsoft, the corresponding alert can then be closed in the sending manager using this ID.

string

location

A set of key-value pairs that specify the physical or virtual location where the event occurred.

When defining locations, it is good practice to use the same conventions for all events. For example, if you want to define virtual locations, use the same event field (such as data_center) and the same location names used by your cloud vendor.

JSON object

tags

Include additional information about an event using the tags key. Specify data as an array or as a series of key-value pairs.

JSON object

dedupe_key

Do not include this field in your event payload unless you want to customize the default deduplication behavior. See Event deduplication: how-to and best practices

string



API Authentication

Moogsoft supports basic and bearer token authentication for programmatic access to our public APIs.

Basic authentication

Embed the username and API key in the URL using the format username:api_key@domain_name. For example:

curl -k "https://my-username:my-api-key_!bmf0u446-7345-297j-3769-g57rs8qqztm@api.moogsoft.ai/v1/integrations/metrics"\
    -H "Content-Type: application/json"
    -d '{ "metric": "your-metric", "data": 10, "source": "www.your-source.com", "key": "dev", "tags": { "key": "value" }, "utc_offset": "GMT-07:00"}'

Bearer token authentication

Include the API key as a header in the body of the HTTP request. For example:

curl -k "https://api.moogsoft.ai/v1/integrations/metrics"\
    -H "Content-Type: application/json"
    -H 'apiKey: mynamespace_!bmf0u446-7345-297j-3769-g57rs8qqztm'
    -d '{ "metric": "your-metric", "data": 10, "source": "www.your-source.com", "key": "dev", "tags": { "key": "value" }, "utc_offset": "GMT-07:00"}'

Events API specification

In this section: