Development¶

API¶

Self-Monitoring API¶

The monitoring endpoints allow you to monitor the health of Tornado. They provide information about the status, activities, logs and metrics of a running Tornado instance. Specifically, they return statistics about latency, traffic, and errors.

Available endpoints:

Ping endpoint

This endpoint returns a simple message “pong - “ followed by the current date in ISO 8601 format.

Details:

name : ping
path : /monitoring/ping
response type: JSON

response example:

{
  "message": "pong - 2019-04-12T10:11:31.300075398+02:00",
}

Metrics endpoint

This endpoint returns Tornado metrics in the Prometheus text format Details:

name : metrics/prometheus
path : /monitoring/v1/metrics/prometheus
response type: Prometheus text format

response example:

# HELP events_processed_counter Events processed count
# TYPE events_processed_counter counter
events_processed_counter{app="tornado",event_type="icinga_process-check-result"} 1
# HELP events_processed_duration_seconds Events processed duration
# TYPE events_processed_duration_seconds histogram
events_processed_duration_seconds_bucket{app="tornado",event_type="icinga_process-check-result",le="0.5"} 1
events_processed_duration_seconds_bucket{app="tornado",event_type="icinga_process-check-result",le="0.9"} 1
events_processed_duration_seconds_bucket{app="tornado",event_type="icinga_process-check-result",le="0.99"} 1
events_processed_duration_seconds_bucket{app="tornado",event_type="icinga_process-check-result",le="+Inf"} 1
events_processed_duration_seconds_sum{app="tornado",event_type="icinga_process-check-result"} 0.000696327
events_processed_duration_seconds_count{app="tornado",event_type="icinga_process-check-result"} 1
# HELP events_received_counter Events received count
# TYPE events_received_counter counter
events_received_counter{app="tornado",event_type="icinga_process-check-result",source="http"} 1
# HELP http_requests_counter HTTP requests count
# TYPE http_requests_counter counter
http_requests_counter{app="tornado"} 1
# HELP http_requests_duration_secs HTTP requests duration
# TYPE http_requests_duration_secs histogram
http_requests_duration_secs_bucket{app="tornado",le="0.5"} 1
http_requests_duration_secs_bucket{app="tornado",le="0.9"} 1
http_requests_duration_secs_bucket{app="tornado",le="0.99"} 1
http_requests_duration_secs_bucket{app="tornado",le="+Inf"} 1
http_requests_duration_secs_sum{app="tornado"} 0.001695673
http_requests_duration_secs_count{app="tornado"} 1

The following metrics are provided:

events_received_counter : total number of received events grouped by source (nats, tcp, http) and event type
events_processed_counter : total number of processed events grouped by event type
events_processed_duration_seconds_sum : total time spent for event processing
events_processed_duration_seconds_count : total number of processed events
invalid_events_received_counter : total number of received event with a not valid format. This can be caused, for example, by a not valid JSON representation or by the missing of mandatory fields
actions_received_counter : total number of received actions grouped by type
actions_processed_counter : total number of processed actions grouped by type and outcome (failure or success)
actions_processing_attempts_counter : total number of attempts to execute an action grouped by type and outcome (failure or success). This number can be greater than the total number of received actions because the execution of a single action can be attempted multiple times based on the defined Retry Strategy

Many other metrics can be derived from these ones, for example:

events_processed_counter - events_received_counter = events waiting to be processed
events_processed_duration_seconds_sum / events_processed_duration_seconds_count = mean processing time for an event

Tornado Backend API v1¶

The Tornado Backend contains endpoints that allow you to interact with Tornado through REST endpoints.

In this section we describe the version 1 of the Tornado Backend APIs.

Tornado ‘Auth’ Backend API¶

The ‘auth’ APIs require the caller to pass an authorization token in the headers in the format:

Authorization : Bearer TOKEN_HERE

The token should be a base64 encoded JSON with this user data:

{
  "user": "THE_USER_IDENTIFIER",
  "roles": ["ROLE_1", "ROLE_2", "ROLE_2"]
}

In the coming releases the current token format will be replaced by a JSON Web Token (JWT).

Tornado ‘Config’ Backend API¶

The ‘config’ APIs require the caller to pass an authorization token in the headers as in the ‘auth’ API.

Working with configuration and drafts

These endpoints allow working with the configuration and the drafts

Endpoint: get the current Tornado configuration

HTTP Method: GET
path : /api/v1_beta/config/current
response type: JSON

response example:

{
  "type": "Rules",
  "rules": [
    {
      "name": "all_emails",
      "description": "This matches all emails",
      "continue": true,
      "active": true,
      "constraint": {
        "WHERE": {
          "type": "AND",
          "operators": [
            {
              "type": "equal",
              "first": "${event.type}",
              "second": "email"
            }
          ]
        },
        "WITH": {}
      },
      "actions": [
        {
          "id": "Logger",
          "payload": {
            "subject": "${event.payload.subject}",
            "type": "${event.type}"
          }
        }
      ]
    }
  ]
}

Endpoint: get list of draft ids

HTTP Method: GET
path : /api/v1_beta/config/drafts
response type: JSON
response: An array of String ids
response example:
```
["id1", "id2"]
```

Endpoint: get a draft by id

HTTP Method: GET
path : /api/v1_beta/config/drafts/{draft_id}
response type: JSON
response: the draft content

response example:

{
  "type": "Rules",
  "rules": [
    {
      "name": "all_emails",
      "description": "This matches all emails",
      "continue": true,
      "active": true,
      "constraint": {
        "WHERE": {},
        "WITH": {}
      },
      "actions": []
    }
  ]
}

Endpoint: create a new draft and return the draft id. The new draft is an exact copy of the current configuration; anyway, a root Filter node is added if not present.

HTTP Method: POST
path : /api/v1_beta/config/drafts
response type: JSON
response: the draft content
response example:
```
{
  "id": "id3"
}
```

Endpoint: update an existing draft

HTTP Method: PUT
path : /api/v1_beta/config/drafts/{draft_id}
request body type: JSON
request body: The draft content in the same JSON format returned by the GET /api/v1_beta/config/drafts/{draft_id} endpoint
response type: JSON
response: an empty json object

Endpoint: delete an existing draft

HTTP Method: DELETE
path : /api/v1_beta/config/drafts/{draft_id}
response type: JSON
response: an empty json object

Endpoint: take over an existing draft

HTTP Method: POST
path : /api/v1_beta/config/drafts/{draft_id}/take_over
response type: JSON
response: an empty json object

Endpoint: deploy an existing draft

HTTP Method: POST
path : /api/v1_beta/config/drafts/{draft_id}/deploy
response type: JSON
response: an empty json object

Tornado ‘Event’ Backend API¶

Send Test Event Endpoint

Endpoint: match an event on the current Tornado Engine configuration

HTTP Method: POST
path : /api/v1_beta/event/current/send
request type: JSON
request example:
```
{
    "event": {
      "type": "the_event_type",
      "created_ms": 123456,
      "payload": {
        "value_one": "something",
        "value_two": "something_else"
      }
    },
    "process_type": "SkipActions"
}
```
Where the event has the following structure:
- type: The Event type identifier
- created_ms: The Event creation timestamp in milliseconds since January 1, 1970 UTC
- payload: A Map<String, Value> with event-specific data
- process_type: Can be Full or SkipActions:
  - Full: The event is processed and linked actions are executed
  - SkipActions: The event is processed but actions are not executed
response type: JSON

response example:

{
 "event": {
   "type": "the_event_type",
   "created_ms": 123456,
   "payload": {
     "value_one": "something",
     "value_two": "something_else"
   }
 },
 "result": {
   "type": "Rules",
   "rules": {
     "rules": {
       "emails_with_temperature": {
         "rule_name": "emails",
         "status": "NotMatched",
         "actions": [],
         "message": null
       },
       "archive_all": {
         "rule_name": "archive_all",
         "status": "Matched",
         "actions": [
           {
             "id": "archive",
             "payload": {
               "archive_type": "one",
               "event": {
                 "created_ms": 123456,
                 "payload": {
                   "value_one": "something",
                   "value_two": "something_else"
                 },
                 "type": "the_event_type"
               }
             }
           }
         ],
         "message": null
       }
     },
     "extracted_vars": {}
   }
 }
}

Endpoint: match an event on a specific Tornado draft

HTTP Method: POST
path : /api/v1_beta/event/drafts/{draft_id}/send
request type: JSON
request/response example: same request and response of the /api/v1_beta/event/current/send endpoint

Tornado ‘RuntimeConfig’ Backend API¶

These endpoints allow inspecting and changing the Tornado configuration at runtime. Please note that whatever configuration change performed with these endpoints will be lost when Tornado is restarted.

Get the logger configuration

Endpoint: get the current logger level configuration

HTTP Method: GET
path: /api/v1_beta/runtime_config/logger
response type: JSON

response example:

{
  "level": "info",
  "stdout_enabled": true,
  "apm_enabled": false
}

Set the logger level

Endpoint: set the current logger level configuration

HTTP Method: POST
path: /api/v1_beta/runtime_config/logger/level
response: http status code 200 if the request was performed correctly
request body type: JSON
request body:
```
{
  "level": "warn,
  tornado=trace"
}
```

Set the logger stdout output

Endpoint: Enable or disable the logger stdout output

HTTP Method: POST
path: /api/v1_beta/runtime_config/logger/stdout
response: http status code 200 if the request was performed correctly
request body type: JSON
request body:
```
{
  "enabled": true
}
```

Set the logger output to Elastic APM

Endpoint: Enable or disable the logger output to Elastic APM

HTTP Method: POST
path: /api/v1_beta/runtime_config/logger/apm
response: http status code 200 if the request was performed correctly
request body type: JSON
request body:
```
{
  "enabled": true
}
```

Set the logger configuration with priority to Elastic APM

Endpoint: This will disable the stdout and enable the Elastic APM logger; in addition, the logger level will be set to the one provided, or to “info,tornado=debug” if not present.

HTTP Method: POST
path: /api/v1_beta/runtime_config/logger/set_apm_priority_configuration
response: http status code 200 if the request was performed correctly
request body type: JSON
request body:

{
  "logger_level": true
}

Set the logger configuration with priority to stdout

Endpoint: this will disable the Elastic APM logger and enable the stdout; in addition, the logger level will be set to the one provided in the configuration file.

HTTP Method: POST
path: /api/v1_beta/runtime_config/logger/set_stdout_priority_configuration
response: http status code 200 if the request was performed correctly
request body type: JSON
request body:
```
{}
```

Set the Smart Monitoring Executor status

Endpoint: this activates and deactivates the Smart Monitoring Executor. When the Executor is in active state, it will execute incoming Actions as soon as they are produced. When instead the Executor is in inactive state, all incoming Actions will be queued until the Executor returns in active state.

HTTP Method: POST
path: /api/v1_beta/runtime_config/executor/smart_monitoring
response: http status code 200 if the request was performed correctly
request body type: JSON
request body:
```
{
   "active": false
}
```