Real-Time Metrics

Real-time metrics show necessary information about the current status of an Omilia Application. They are created from a specific selection of Omilia KPIs, targeted to ensure the user is informed about the current state of their system, without being overwhelmed with information. These metrics will be publicly available through the Metrics API.

OCP® Analytics APIs

Metrics API

Metrics API is organized around HTTP REST. Our API currently offers two endpoints to serve parametrized and daily metric requests and uses HTTP response codes to indicate API errors.

  • Endpoint 1
    Daily requests fetch the data from midnight of the day the request is made to the moment the request is filled.

  • Endpoint 2
    Hourly metrics, for which requests are filled using a call to a non-daily endpoint with a specific start/end time.

The highest granularity of metrics will be five minutes, which is also the default, but with the downsampling parameter, the user can apply a custom sampling rate. For example, request hourly metrics for the last 24 hours.

Authentication

Authenticate by including your secret API key in all requests. Your API keys carry many privileges, so be sure to keep them secret! Do not share this data in publicly accessible areas such as Github, client-side code, and so forth.

There are two types of API keys, depending on the privileges they carry:

  • admin API keys - authorized to fully manage and query OCP resources, i.e. create, update, delete and list resources

  • application API keys - authorized to only query the OCP resource that they belong to

admin API keys are provided by Omilia and application API keys are generated when creating the respective resource

Include the desired API key in the HTTP Authorization header using the following authorization scheme.

Sample request:

curl -v -X GET {service_url} \
  -H "Authorization: Token {api_key}" \
  -H "Content-Type:application/json"
BASH

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

The API provides a generic error response for every endpoint in the following format:

{
  "error": <true|false>,
  "code": <error_code>,
  "message": "some message pointing to a specific erroneous situation"
}
JSON

Omilia uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (for example, a required parameter was omitted, and so on), and codes in the 5xx range indicate an error with Omilia’s servers.

However, not all errors map cleanly onto HTTP response codes. To understand the source of the error please refer to the list of codes in the documentation.

The Omilia API uses the following error codes:

HTTP Error Codes

Error Code

Meaning

200

OK Everything worked as expected

400

Bad Request The request was unacceptable, often due to missing or invalid parameters

401

Unauthorized Invalid API key provided

403

Forbidden The provided API key is not authorized to access this resource

404

Not Found The requested resource doesn’t exist

409

Conflict The request conflicts with another request

429

Too Many Requests Too many requests sent to the API in a specific timeframe

500, 502, 503, 504

Server Errors Something went wrong on Omilia’s servers

Metrics types

There are two types of metrics that will be supported:

  • Real-time metrics, are generated in real-time and are broken down into five-minute intervals. Available in Version 1.

  • Non-real-time metrics, (or batch metrics), which are exported from DWH. Those metrics are already offered in Convo Insights. Will be available in future versions of Metrics API.

The metrics will be available through two different endpoints. Version 1 will include the endpoint for real-time metrics only.

Real-Time and Non-Real-Time Metrics

The highest granularity of real-time metrics will be in five-minute intervals. For example, the end user will be able to see the number of invocations between 10:00-10:05, 10:05-10:10, and so on. On the other hand, non-real-time metrics (or batch metrics) will be aggregated on an hourly basis, the same as existing Convo Insights Solutions. For example, the user will be able to view total invocations between 10:00-11:00 and then 11:00-12:00. Both of these metrics will be able to be aggregated on a higher level.

Meaning for real-time and non-real-time metrics the end user will be able to fetch total invocations over the last two hours. Some discrepancy between real-time and batch metrics is expected. One reason is due to real-time metrics having a five minutes watermark after the dialog ended. In some cases, that data delay longer than that mark, and those dialogs won’t be taken into account for real-time reporting. On the other hand, batch metrics take longer to produce in order to retrieve data, even if they were sent with some delay, ensuring their accuracy. A simple example of a data sequence will be available.

Path Parameters

Property

Type

Required

Description

group

string

Yes

The group (organization) the metrics requested belong to. Possible values: ocp

metric-type

string

Yes

The type of metric requested. Possible values: batch, realtime

Query Payload Fields

Property

Type

Required

Description

metrics

array(string)

Yes

List of metrics requested. Available metrics of version 1 can be found in the following section

start

string

Yes

Query start date.

This field value is limited by query-max-age configuration in metrics-api config.

Supported date formats:

  • Relative:

    • <number><units>-ago (units: m = minutes, h = hours, d = days, w = weeks, n = months, y = years)

  • Absolute:

    • yyyy/MM/dd (start of day)

    • yyyy/MM/dd-HH:mm

    • yyyy/MM/dd HH:mm

    • yyyy/MM/dd-HH:mm:ss

    • yyyy/MM/dd HH:mm:ss

Possible values:

  • 1d-ago

  • 2022/01/01 07:00:00

end

string

No

Query end date

Supported date formats:

  • Relative:

    • <number><units>-ago (units: m = minutes, h = hours, d = days, w = weeks n = months, y = years)

    • now (current datetime)

  • Absolute:

    • yyyy/MM/dd (start of day)

    • yyyy/MM/dd-HH:mm

    • yyyy/MM/dd HH:mm

    • yyyy/MM/dd-HH:mm:ss

    • yyyy/MM/dd HH:mm:ss

Possible values:

  • 30m-ago

  • 2022/01/01 07:00:00

  • now (default)

filters.miniappName

array(string)

No

List of miniapp names for the metrics requested. Possible values:

  • appname1 - filters metrics for app1

  • appname1","appname2 - filters metrics for appname1 and appname2

filters.miniappType

array(string)

No

List of miniappTypes for the metrics requested. Possible values:

  • miniapptype1 - filters metrics for miniappType1

  • miniappType1,miniappType2 - filters metrics for miniappType1 and miniappType2

filters.locale

array(string

No

Filter locale for metrics requested. Possible values:

  • en-US - filters metrics for locale en-US

  • en-US,fr-CA - filters metrics for locales en-US and fr-CA

Default value: If absent, will aggregate all locales for metrics requested.

filters.channel

array(string)

No

Filter channel for metrics requested. Possible values:

  • channel1 - filters metrics for channel: channel1

  • channel1 , channel2 - filters metrics for channel1 and channel2

filters.testFlag

boolean

No

Filter test flag for metrics requested. Possible values:

  • false - filters metrics test_flag = false

filters.drilldown

boolean

No

Apply downsampling using interval and algorithm. Possible values:

  • true - for all opentsdb results shows a drilldown (groupBy) using the provided tag value filters

  • false - aggregates opentsdb results in a single time series for the provided filters

timezone

string

No

Possible values:

  • Europe/Athens - use this timezone for start of day to compute daily aggregated counts for metrics requested

Default timezone: UTC

Metrics API Example

Request

POST /metrics-api/{group}/{metric-type}/daily-miniapp-query
JSON

Response

{
    "metrics":["error_tasks_batch"],
    "filters": {
      "miniappName":["car_retail_test"],
      "miniappType":["CarRetail"],
      "locale": "en-US"
    },
    "drilldown": "true",
    "timezone": "timezone"
}
JSON

List of Real-Time Metrics

This set of near real-time metrics will be available in Metrics API v1.0. Apart from the description, there is a list of metrics parameters, also listed above, the user can use to aggregate, drill in, and out of.

Name

Description

Supported Filters (Query Parameters)

Unsupported Filters

session.initiated

Total number of sessions the application received. Sessions refer to either unique IVR Calls or Chat Sessions (depending on the application), no matter how many miniApps or even Orchestrator flows were triggered. A session is counted when the first miniApp is triggered within OCP®. The sessions are recounted for each five-minute interval while they are still active.

start, end, locale(language), channel, testFlag, drilldown, timezone.

miniappName and miniappType.

Note: miniappName and miniappType are not applicable for Session metrics, as a single session triggers multiple miniApps.

dialog.completed

Total number of dialogs per Orchestrator root application. A dialog is a unique conversation (or call for IVR) within an application. This metric will be counted when Orchestrator root application is completed.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

Note: For Dialog metrics, miniappType = 'Flow' is only supported

dialog.transferred

Total number of dialogs per Orchestrator application that got transferred. This metric will be counted when Orchestrator root application is completed in order to retrieve the End Type and is applicable to IVR applications only.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

Note: For Dialog metrics, miniappType = 'Flow' is only supported

dialog.terminated

Total number of dialogs per Orchestrator application that got terminated. This metric will be counted when the Orchestrator root application is completed in order to retrieve the End Type and is applicable to IVR applications only.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

Note: For Dialog metrics, miniappType = 'Flow' is only supported

miniapp.invocations

The number of total invocations of each miniApp a flow/application or standalone The miniApp is counted upon completion of this task.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

miniapp.invocations_successful

The number of total successful invocations of each miniApp within a flow/application or standalone. The miniApp has Result:success.The miniApp has to be completed in order for us to know if it was successful.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

miniapp.system_errors

Total number of invocations per miniApp that ended with a system error, critical error or timeout error.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType

miniapp.no_matches

Total NoMatches per miniApp. A single miniApp may have multiple steps with no matches. This is a per-step metric.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

miniapp.no_inputs

Total No inputs per miniApp. A single miniApp may have multiple steps with no inputs. This is a per-step metric.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

miniapp.critical_error

Number of CriticalError events for each application. A Critical Error event may affect one or multiple miniApps within the same call.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

Time Series Example

The following example will help the end user understand how a Production Call with multiple steps and miniApps would be depicted in real-time metrics. We have a Banking IVR Application, built using Orchestrator. The main flow consists of a sequence of three miniApps. A call enters our IVR at 10:01 and exits the IVR at 10:08. During this call three miniApps are used:

  • miniApp 1 is triggered the moment the call reaches the application,

  • miniApp 2 is triggered at 10:02 after miniApp 1 is completed,

  • miniApp 3 is triggered from 10:06 until 10:08 when the call is terminated.

Real-Time Metrics Intervals

Real-time metrics are split into five-minute intervals. For this example the call will be active for the following two intervals:

  • A: 10:00- 10:05
    In the Insights graph it will be marked as Time Point: 10:05

  • B: 10:05-10:10
    In the Insights graph it will be marked as Time Point: 10:10

Metrics Outputs

  • miniApp1 Invocation will be added at time frame A after 10:02

  • miniApp2 Invocation will be added at time frame A after 10:06

  • miniApp3 Invocation will be added at time frame B after 10:08

  • This session initiated will be added at time frame A after 10:02

  • This Application/Dialog will be added at time frame A after 10:08

  • If this call is transferred out from IVR will be added in Dialogs Transferred at time frame A after 10:08

  • If miniApp2 has three steps with noMatches, they will be added in time frame A, sequentially, meaning the counter could be increasing as more matches are occurring for the same miniApp.

  • If miniApp2 is successful will be added in miniApp successful invocations at time frame A after 10

  • If miniAppa2 has a delay in sending the data for more than five minutes (aka the miniApp ends at 10:06 but the JSON file is sent after 10:11) then it won’t be reported in real-time metrics, due to a five-minute watermark, but all data regardless delay will be captured in Convo Insights, in batch (historical) reporting.

  • There could be a request for miniApps Invocations for Time Interval A, Time Interval B, and also for Time Interval A+B (10:00-10:10), the last 10 minutes.

  • The sessions initiated will be added also at time frame B after 10:08, as the session was still active in that time frame and triggered a new miniApp.

Available Period for Real-Time Metrics

Real-time metrics will have a limited retention period of 48 hours. After this time range the metrics can be monitored, through Conversational Insights. For historical data, the user will be able to monitor their Applications through Convo Insights. In future versions of Metrics API, historical metrics will be also available, but instead of five-minute intervals, they will have one-hour intervals. The historical metrics will be reachable through a different endpoint.

OCP® Reporting for Real-Time Metrics

Metrics available through Metrics API are also available in Reporting UI within OCP® Insights. For more information, refer to the OCP® Reporting User Guide.