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:
Go to the Moogsoft web UI > Data Config > Integrations > Events API and determine the data fields that you want to ingest.
In the external tool, do the following:
Determine the event types that you want to send to Moogsoft.
Set up the tool to trigger alerts for the infrastructure issues of interest.
Set up the tool to send events to the Events API endpoint in the required format.
Event 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:
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:
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 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 | JSON array |
check | REQUIRED The performance, health, or other check that triggered the event. Examples include If two events involve different problems on the same source and service, they should belong to different alerts. For this reason, the | 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:
| 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 | 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"}'