HTTP APIs#

You can query the Logging service by using a REST API. The logs endpoint is authenticated using Unity Service Accounts.

Requesting logs#

Make a GET request to the Logging API.

• The Observability API documentation contains a detailed description of operations for querying logs.

• Refer to Authentication for more information on how to authenticate.

Example cURL command:

curl https://services.api.unity.com/observability/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/logs \
--header 'Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS_ENCODED>' \
--url-query 'from=<TIME_FROM>' \
--url-query 'to=<TIME_TO>' \
--url-query 'query=<FILTER_EXPRESSION>' \
--url-query 'limit=<LIMIT>' \
--url-query 'offset=<OFFSET>'

The following optional query parameters are available:

• from: a RFC3339 timestamp used to specify the starting timestamp of the records to return. For example, 2023-06-29T11:30:22.939Z.
• to: a RFC3339 timestamp used to specify the ending timestamp of the records to return.
• query: a boolean expression for filtering. Refer to Filter logs for more information.
• limit: a positive integer to serve as the maximum number of records to return. Must be less than or equal to 100.
• offset: a positive integer to serve as the offset number of logs from the first result of the query.

Relative time ranges#

The API also supports relative time expressions for the from and to parameters to make working with time ranges easier.

The basic syntax of consists of the following components:

• Base time: Either an RFC3999 timestamp or the now keyword.
• Operator: Either + or -.
• Time offset: An integer and a unit for days, hours, minutes, or seconds, e.g. 12d, 5h, 3m, 17s.

Some examples:

• from=now-30m
• from=2023-08-29T11:30:00.000Z+30s
• from=now-2d&to=now-6h

Example API call#

The following example shows how to query logs from the Logging API using cURL.

Refer to Authentication for more information on how to authenticate.

curl https://services.api.unity.com/observability/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/logs \
--header 'Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS_ENCODED>' \
--url-query 'from=2023-09-01T00:00:00.000Z' \
--url-query 'to=2023-09-01T13:50:00.000Z' \
--url-query 'query=body~=”regular” AND logAttributes.example.myKey=”foo”' \
--url-query 'limit=10' \
--url-query 'offset=0'

The response could look as follows:

{
   "limit" : 10,
   "offset" : 0,
   "total" : 600,
   "results" : [
      {
         "severityNumber" : 9,
         "severityText" : "Information",
         "timestamp" : "2023-09-01T10:45:00.445Z",
         "body" : "this is just a regular log message",
         "logAttributes" : {
            "example.myKey" : "foo",
            "log.record.uid" : "a566701a-a9e5-42f7-bd8e-013fa9ef1afa",
            "unity.environmentId" : "c288f9e5-423b-4150-a982-5a1a40b1219a",
            "unity.projectId" : "2af24fd0-f224-499e-8768-07b54c693aee"
         },
         "resourceAttributes" : {
            "service.name" : "cloud-code"
         }
      }
   ]
}

The response contains the following fields:

• limit: the maximum number of records returned.
• offset: the offset number of logs from the first result of the query.
• total: the total number of records that match the query.
• results: an array of log entries.

The results array objects map to the log schema.