Example scenario for CYOI

This example illustrates how to create a custom API using Create your own integration (CYOI) that ingests raw events from an third-party service and automatically converts the data to Moogsoft-compatible events.

You're a DevOps engineer responsible for setting up Moogsoft. Your team uses an open-source tool called mooMON to monitor your infrastructure and applications. You have mooMON set up to post API notifications whenever an event of operational significance occurs.

This example is part of an overall end-to-end workflow for setting up Moogsoft:

  1. In this example, you set up a custom ingestion to ingest your events.

  2. Then you create an events workflow that formats your events into useful alerts.

  3. Finally, you set up a correlation to cluster the resulting alerts into useful incidents.

Compare schemas

Moogsoft uses two different schemas, one for events and one for metrics, to store and process incoming data. To ingest your data, you need to map the mooMon data fields to their equivalents in the Moogsoft events schema.

Moogsoft events schema (required fields)

{
    "description": "CPU spike to 75%",
    "severity": 4,
    "source": "www.your-source.com",
    "check": "cpu",
    "service": [
        "retail",
        "support"
    ]
}

You review the Moogsoft Events API. You note that the fields shown above are required. You need to identify which Moogsoft fields have mooMON equivalents and which fields do not. Comparing the two schemas, you notice the following:

  • The source and service fields do not have mooMON equivalents. This is not a problem: you can put in placeholders for now. Later, you can create an automated workflow to enrich the mooMON events after they get ingested.

  • The mooMON schema includes a metadata field with a lot of useful information. This field doesn't have a Moogsoft equivalent. You can map this to a tag when you set up your custom integration.

Table 2. Moogsoft and mooMON field mapping

MoogsoftFields

mooMON fields

Comments

description

trigger_condition

severity

trigger_severity

source

No equivalent. The event source is embedded in the mooMON metadata field, for example:

["ip=172.31.17.101,hostName=websrv01.us=west.myorg.org, id=125989934839832182"]

check

trigger_policy

service

No equivalent. The mooMON schema does not include the service associated with the event.



Create and configure a new endpoint

You know how you want to map your mooMON fields to the Moogsoft Events API. You're now ready to create your custom integration. You log in to the Moogsoft UI and do the following:

  1. Choose Data Config > Ingestion Services > Create your own Integration,, then click Add New Integration .

  2. In Configuration Information, specify the following:

    • Endpoint = moomon-events

    • API Description = mooMON Events API

    • Data Type = Events

  3. Click Save. The setup window for your custom integration appears.

Send your mooMON events to the new endpoint

Now you have an endpoint for your custom integration. You update your mooMON service to send data to the custom endpoint.

At this point the endpoint can ingest any POST notification that has a valid JSON payload and the correct API key.

Map your mooMon data fields to Moogsoft

Now that you have events coming into your new endpoint, you return to the Moogsoft. In the Map your Data section, you do the following:

  1. Select a payload in the Payload View table. the selected payload appears in the pane below.

    view-payload.png

    NOTE: If your payloads include multiple events in a list under a top-level object, see Use batch processing with custom integrations for data field mapping instructions.

  2. In the Field Mapping table, you map your fields as follows:

    • For mooMON fields with a one-to-one mapping, map the fields to their Moogsoft equivalents as shown in in Table 2, “Moogsoft and mooMON field mapping above.

    • For the Moogsoft fields source and service, which have no mooMON equivalents, simply enter the string TBD.

      These strings will act as placeholders until you create a workflow that populates these fields with the correct values.

    • Map the metadata field, which has no Moogsoft equivalent, to tags.labels.

    field-mapping.png
  3. In addition to mapping fields, you also need to map the mooMon event severities to their Moogsoft equivalents. You click Map Values and map the severities:

    severity-mapping.png
  4. You return to the setup page for your custom integration, scroll down to the bottom, and click Save and Enable.

    You can also customize how your integration deduplicates events into alerts, but this is an advanced feature and you accept the default settings.

  5. You return to the Custom APIs window. The table shows that your custom API is now active.

    moomon-in-custom-apis-table.png
  6. You go to the Alerts page and see that your mooMon events are now getting converted to alerts.

    There is still one issue: your alerts all have "TBD" as the source and the service.This is not a problem, because the hostnames are contained in the metadata tag. You can create an enrichment workflow to populate these fields. See A workflow configuration example.