Lastline Monitoring API¶

The Lastline Monitoring API is an API for querying monitoring data of Lastline appliances.

The Lastline Monitoring API is accessible at:

https://user.lastline.com/papi/monitoring/<function>

Appliance Selection¶

The Lastline Monitoring API supports multiple ways to select from which appliances to query data.

by appliance_uuid. Every method supports as an optional parameter appliance_uuids which may contain a comma separated list of UUIDs identifying appliances.
by key. Every method accepts an optional key (or key_id and subkey_id) parameter. This allows to query appliances by a given license key.
by appliance_type. Every method supports as an optional parameter appliance_type. This parameter can be set to one of the supported appliance types.

It is possible to use these filter parameters in combination. If any of the provided appliance_uuids does not exist, or the requestor does not have sufficient permissions on the appliance, or the appliance_type parameter is provided with a different type, the API returns an LLAPI_APPLIANCE_MGMT_ERROR__NO_SUCH_APPLIANCE (9003) error.

Metrics: Counters and Gauges¶

The methods list_metric() and get_metric() support counters and gauges.

Gauges represent values at a given point in time. Examples are CPU load, disk usage or memory usage. Counters represent occurrences of an event in a time frame. Examples include files analyzed, emails processed, or network packets received.

Whether a metric returned by list_metric() is a counter or a gauge can be determined by its prefix. It is either counter. or gauge..

Using the method get_metric(), data for counters and gauges can be received. It is important to note that counters are returned as rates. That is, occurrences per second.

Methods¶

Method Index¶

list_metric():

List available metrics.
get_metric():

Get the values of a metric for a set of appliances over a specified time range.
aggregate_metrics():

Aggregate data accross a set of appliances over a specified time range.
get_log():

Get log messages for a set of appliances over a specified time range.
get_log_entry():

Get information about a single log entry.

Method Documentation¶

monitoring.list_metric(response_format)¶

List available metrics.

Get the list of metrics for which there is data for a set of appliances over a specified time range.

URL

/papi/monitoring/metric/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

start_time:

Restrict to metrics reported at least once after this time (required).

end_time:

Restrict to metrics reported at least once before this time (required).

timezone:

Apply this timezone to the required range (default UTC). This parameter can also be called time_zone.

appliance_type:

Restrict to metrics present on appliances of this type. One of SENSOR, MANAGER, ENGINE, PINBOX or ANALYST.

appliance_uuids:

Comma-separated list of uuids. Restrict to metrics present on one of these appliances.

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of main customer (this is an email address). Defaults to the customer for which the current account is authenticated.

Contents of successful response

A list of metric identifiers.

monitoring.get_metric(response_format)¶

Get a metric for one or more appliances over a specified time range.

URL

/papi/monitoring/metric/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

metric:

A metric identifier, as returned by list_metrics (required).

start_time:

Restrict to metrics reported at least once after this time (required).

end_time:

Restrict to metrics reported at least once before this time (required).

timezone:

Apply this timezone to the required range (default UTC). This parameter can also be called time_zone.

appliance_type:

Restrict to metrics present on appliances of this type. One of SENSOR, MANAGER, ENGINE, PINBOX or ANALYST.

appliance_uuids:

Comma-separated list of uuids. Restrict to metrics present on one of these appliances.

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of main customer (this is an email address). Defaults to the customer for which the current account is authenticated.

max_data_points:

Maximum number of data points to return for each time series (that is, for each appliance). If necessary, values in the time series will be aggregated to longer time intervals to achieve this goal. For this, an appropriate aggreagation interval length will be automatically selected. The aggregation interval can be half an hour or or 1, 2, 3, 4, 6, 8, 12, or 24 hours. This value defaults to 150 and is limited to at most 300.

Contents of successful response

Returns a dictionary mapping an appliance UUID to a dictionary with the following keys:

time_series:

List of timestamp, value tuples for the requested metric. When the requested metric represents a counter, the returned values describe the rate per second for this counter.

appliance_type:

The type of the appliance (SENSOR, MANAGER, ENGINE, PINBOX or ANALYST)

access_key:

License key of the appliance (if any)

subkey:

License subkey of the appliance (if any)

subkey_name:

User-assigned, human readable name of subkey (if any)

access_key_id:

Identifier of license key (if any)

subkey_id:

Identifier of subkey (if any)

monitoring.aggregate_metrics(response_format)¶

Aggregate data accross a set of appliances over a specified time range.

Currently, aggregation happens by summing across aplliances. In the future, different aggregation methods may be provided.

URL

/papi/monitoring/metric/aggregate[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

start_time:

Restrict to metrics reported at least once after this time (required).

end_time:

Restrict to metrics reported at least once before this time (required).

metrics:

A comma-separated list of metric identifiers (required).

max_data_points:

Maximum number of data points to return for each requested metric. If necessary, values in the time series will be aggregated to longer time intervals to achieve this goal. For this, an appropriate aggreagation interval length will be automatically selected.

timezone:

Apply this timezone to the required range (default UTC). This parameter can also be called time_zone.

appliance_type:

Restrict to data present on appliances of this type. One of SENSOR, MANAGER, ENGINE, PINBOX or ANALYST.

appliance_uuids:

Comma-separated list of uuids. Restrict to data present on one of these appliances.

key:

access_key[:subkey]: restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

Contents of successful response

A dictionary with keys:

metrics:

Sequence of objects containing the metric identifier in “metrics” and a list of (start_date, value) tuples in “time_series”.

Example:
"metrics": [
    {
        "metric": "name of requested metric",
        "time_series": [
            [ <start_interval1>, <value1> ],
            [ <start_interval2>, <value2> ],
            ...
        ]
    },
    ...
]

monitoring.get_log(response_format)¶

Get logs for one or more appliances over a specified time range.

URL

/papi/monitoring/log/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

start_time:

Restrict to log entries reported at least once after this time (required).

end_time:

Restrict to log entries reported at least once before this time (required).

identifiers:

A comma-separated list of log identifiers (defaults to all).

limit:

Limit response to this many log entries.

timezone:

Apply this timezone to the required range (default UTC). This parameter can also be called time_zone.

appliance_type:

Restrict to log entries present on appliances of this type. One of SENSOR, MANAGER, ENGINE, PINBOX or ANALYST.

appliance_uuids:

Comma-separated list of uuids. Restrict to metrics present on one of these appliances.

key:

access_key[:subkey]: restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of main customer (this is an email address). Defaults to the customer for which the current account is authenticated.

min_impact:

Restrict to log entries with level of impact higher than or equal to this

max_impact:

Restrict to log entries with level of impact lower than or equal to this

message_contains:

Restrict to log entries whose message contains this filter string

components:

Restrict to log entries reported by the specified high level component

Contents of successful response

A dictionary with keys:

log_entries:

Sequence of log entries, sorted from newest to oldest

appliances:

Dictionary mapping appliance_uuid to infrmation about each appliance for which there is an entry in log_entries are available.

log_entry_info:

Additional information about log_entries to aid displaying of entries in log_entries.

Each log entry contains the following fields:

appliance_uuid: uuid of appliance that reported this log entry

start_time: first time a log entry like this one was reported

end_time: last time a log entry like this one was reported

message: log message

impact: impact of this log entry, 0-100

count: number of occurrences of log entries like this one

log_identifier: identifier of this type of log entry

The log_entry_info entry is a dictionary mapping appliance_uuids to another dictionary containing additional information about log entries. The second dictionary is keyed by the log_identifier.

Each such info entry contains the following fields:

component: High-level component the log entry was reported by

displayname: A user-friendly name

description: More detailed description (optional)

Example:
{
    '287a0715712a405abbdc42d826f81fb4': {
        'llmail.analysis.submission': {
            'component': 'Mail',
            'displayname': 'Submission of Artifacts'
        }, ...
    }, ...
}
This information is dependent on the version of each appliance. A log_identifier will not have an entry if there is no additional information available.

monitoring.get_log_entry(response_format)¶

Get detailed information about a single log entry.

URL

/papi/monitoring/log/get_entry[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

log_entry_uuid

Unique identifier of the requested log entry as received by :py:func`get_log`.

timezone:

Apply this timezone to fields start_time and end_time. This parameter can also be called time_zone.

Contents of successful response

A dictionary with an entry for the requested log entry.

Example

{
    'log_entry': {
        'log_entry_uuid': '64360bd07ca044038e7e7a829bd646dd',
        'count': 999,
        'start_time': '2013-09-01 00:05:00',
        'end_time': '2013-09-01 00:05:00',
        'impact': 10,
        'log_identifier': 'db.replication',
        'message': 'OK',
        ...
    }
}

Lastline Monitoring API¶

Appliance Selection¶

Metrics: Counters and Gauges¶

Methods¶

Method Index¶

Method Documentation¶

Table Of Contents

Previous topic

Next topic