VMware Services - VMware Aria Operations for Logs

Getting Started

Welcome to the VMware Aria Operations for Logs API Reference Guide. This guide contains information about the APIs that you can use to interact with VMware Aria Operations for Logs. This information includes API categories, descriptions, endpoints, status codes, rate limiting, and authentication.

API Endpoints

VMware Aria Operations for Logs has several deployments in different geographic locations. You'll need to use the API endpoint corresponding to your geographic location. See the table below for the different API endpoints by deployment.

Authentication

VMware Aria Operations for Logs API supports VMware Cloud Services Platform (CSP) for API authentication.

Obtain a VMware Cloud API Token

Calling APIs requires an API Token and you will need to navigate to the VMware Cloud portal and create a new API Token (requires login). Your API Token will be an alpha-numeric string.

You can learn more about generating an API Token here.

Using API Tokens

Once you have generated an API Token, you will use it to programmatically authorize access to APIs. Before your application can begin calling APIs, it must first make a POST request to the Cloud Services Platform (CSP) using your API Token passed with a content type of "application/x-www-form-urlencoded". Here is an example in curl. Ensure that you replace the refresh token value with your API token value.

curl --location --request POST 'https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token=dmDH3qSAuyljYajcvHz267Of4iVSN9VjiaxzEZ223qEaGdpe0vOqIASknYKv58JT'

The CSP authorize API call will return an access_token along with additional details associated with the API Token as follows:

{
    "id_token": "...",
    "token_type": "bearer",
    "expires_in": 1799,
    "scope": "openid group_ids group_names",
    "access_token": "...",
    "refresh_token": "..."
}

In the response above, the access_token will be a character string which you will need to include as an HTTP header on all subsequent API calls using the key “Authorization Bearer” as follows:

Content-Type: application/json
Authorization: Bearer <access_token_value>

Handling access_token Expiration

As part of the CSP authorize API, you will receive an expires_in key indicating the number of seconds before the access_token will expire. After this expiration period, subsequent calls to any VMware Cloud API will return the following error:

{
    "timestamp": "2020-01-02T17:11:01.223+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Auth token is not valid"
}

When an API call fails with the above error, your script/program can request for a new access_token using the refresh_token provided in the initial CSP authorize call (see above). Then, you can use the same access_token to authorize the API.

Status Codes

Refer the following table for generic status codes that apply to all the APIs. For more information, see the HTTP status code registry.

Limits

Rate Limiting/Concurrency

VMware Aria Operations for Logs supports up to 240 API calls per tenant per minute. You can run a maximum of 15 instances of each API concurrently.

Usage Limits for Features

Refer the following table to know about the usage limits per subscription for various features in VMware Aria Operations for Logs.

Query Async Service

To query logs, make a POST call that returns a URL to fetch the actual logs. Then, make a GET call on the URL to receive logs and the next page link. You can make only one GET call per second for a query.

1. Make a POST call on the log query. On success, you will get back a URL in the response to fetch the logs.

{
  "documentSelfLink": "/vrlic/api/v1/query/<queryID>",
  "logQuery": "SELECT * FROM logs ORDER BY ingest_timestamp DESC"
}

2. Make a GET call on the above URL, that you get as a documentSelfLink to receive logs and the next page link.

{
  "nextPageLink": "/vrlic/api/v1/query/<queryID>?nextPage",
  "logQuery": "SELECT * FROM logs ORDER BY ingest_timestamp DESC"
}

Note: You can again make a GET call on the above nexPageLink to fetch the next set of logs, if present.

3. During the second GET call, you will be able to move to the previous page using the prev link.

 "_links": {
    "next": {
      "href": "/vrlic/api/v1/query/<queryID><pageNumber>?nextPage"
    },
    "prev": {
      "href": "/vrlic/api/v1/query/<queryID>"
    },
    "self": {
      "href": "/vrlic/api/v1/query/<queryID><pageNumber>"
    },
    "first": {
      "href": "/vrlic/api/v1/query/<queryID>"
    }
  }

See the Log Query section for more information about the GET/POST call.

Alert Instance Async Service

To get alert instances, make a POST call that returns a nextPageLink. Then, make another POST call with the same nextPageLink as a request body that returns alert instance collection for an org. Then, make a GET call on the selfLink to receive an alert Instance by ID.

1. Make a POST call on an alert instance. On success, you will get back a nextPageLink in the response.

{
  "nextPageLink": "/vrlic/api/v1/query/<queryID>?nextPage",
}

2. Make another POST call on an alert instance with the above nextPageLink as a request body. On success, you will get back an alert Instance collection in the response.

{
  "alertInstanceColl": [
        {
            "selfLink": "/vrlic/api/v1/alert/instances/<queryID>",
             ...
        },
        {
            "selfLink": "/vrlic/api/v1/alert/instances/<queryID>",
             ...
        }
}

3. Make a GET call on the above URL, which you get as a selfLink to receive an alert Instance by ID.

See the Alert Instances section for more information about the GET/POST call.