URL Query Parameters

URL Query Parameters provide a convenient way to customize and share data with your applications. By leveraging these parameters, you can control time ranges, apply filters, and configure various settings for Dashboards, Datasets, Resource Instances, and Worksheets. This flexibility allows for seamless integration and enhanced data exploration within the Observe platform.

Formatting a URL Query

The URL for an Observe object is composed this way:

https://${Customer_ID}.observeinc.com/workspace/${Instance_ID}/${PATH}/${Object_Name}?${KEY-VALUE_PARAMETER}&${KEY-VALUE_PARAMETER}

Object names, IDs, and parameters like versions differ between object types; check the URLs displayed by the browser when you use the Observe interface to view the object.

For example, the URL "https://${Customer_ID}.observeinc.com/workspace/${INSTANCE_ID}/dataset/event/System-${Object_ID}?time-end=1683675692262" links to the System event dataset in your instance with an end time of Tuesday, May 9, 2023 23:41:32.262 UTC.

Additional parameters can be added to the URL after an & character.

For example, the URL "https://${Customer_ID}.observeinc.com/workspace/${INSTANCE_ID}/dataset/event/System-${Object_ID}?time-end=1683675692262&time-start=1683561222716" links to the System event dataset in your instance with a start time of Monday, May 8, 2023 19:53:42.716 UTC and end time of Tuesday, May 9, 2023 23:41:32.262 UTC.

You can use these parameters to create deep links into your Observe instance. For instance, you may want to add a link to a troubleshooting Dashboard to a team resources page so team members don’t have to start at the Observe home page and browse to it. Your link HTML code may look something like the following:

<html>
<p>
<a href="https://123456789012.observeinc.com/workspace/41000009/dataset/event/Container-Logs-41007104?filter-status=error">Container Logs Dataset with Filter Status = Error</a>
</p>
</html>

Note

Observe recommends URL Encoding all URL parameter keys and values when creating a URL string. Some browsers accept unencoded URLs, but this behavior may be unreliable. For best results, URL encode query string parameter keys and values.

URLs generated by Observe while viewing objects in the browser are properly encoded and can be used as examples.

The following tables list the currently supported URL Parameters:

Time Ranges

Time filters are very important in Observe. Precise selection of time ranges improves performance and cost impact while ensuring the user gets the data that they need. Observe URL timestamps can be specified in ISO 8601 or Unix epoch format.

Parameter

Description

time-start

Include data after this time

time-end

Do not include data after this time

time-preset

Include data matching this preset

Example Date and Time Formats

Time Start Example

Description

?time-start=1686165391864

Unix epoch timestamp in milliseconds (UTC time)

?time-start=2023-06-07T15:08:07Z

ISO 8601 string specified in UTC time

?time-start=2023-06-07T15:02:31-04:00

ISO 8601 string with a timezone offset specified

Note

When using an ISO 8601 string you may replace the : with . in the URL for an easier-to-read format. The . does not have to be URI encoded. For example:?time-start=2023-06-07T15.02.31-04.00

This option is not available with formatting for sub-second precision, which also uses a . character.

The time-preset parameter supports the following preset keys:

  • TODAY

  • YESTERDAY

  • THIS_DAY_LAST_WEEK

  • LAST_WEEK

  • LAST_MONTH

  • PAST_5_MINUTES

  • PAST_10_MINUTES

  • PAST_15_MINUTES

  • PAST_30_MINUTES

  • PAST_60_MINUTES

  • PAST_2_HOURS

  • PAST_4_HOURS

  • PAST_6_HOURS

  • PAST_12_HOURS

  • PAST_24_HOURS

  • PAST_2_DAYS

  • PAST_3_DAYS

  • PAST_4_DAYS

  • PAST_7_DAYS

  • PAST_14_DAYS

  • PAST_30_DAYS

Filters

Constructing filters is a critical function for using pre-built custom Observe URLs. Different Observe pages and objects have different filtration needs and capabilities. You can use Filters on the following types of pages:

  • Explorers, such as Log Explorer

  • Dashboards, such as Observe Usage/Compute Utilization User Breakdown

  • Worksheets

  • Lists, such as the Dashboard list

Filters are composed of three parts: the key, or column that you want to test, the operator, and the value. Operators are bracketed with | pipe characters. Supported operators are:

Operator

Description

URL Encoded Example

=

Equal

filter=OBSERVATION_KIND%7C%3D%7Csystem

!=

Not Equal

filter=OBSERVATION_KIND%7C%21%3D%7Csystem

~

Contains

filter=OBSERVATION_KIND%7C~%7Csystem

!~

Does Not Contain

filter=OBSERVATION_KIND%%7C%21~%7Csystem

>

Greater than

filter=record_count%7C>%7C100

<

Less than

filter=record_count%7C<%7C100

>=

Greater than or Equal to

filter=record_count%7C>%3D%7C100

<=

Less than or Equal to

filter=record_count%7C<%3D%7C100

For simplicity and readability, when using the operator = (Equals) you may use the “short-hand” parameter specification, filter-<key>=value. Otherwise, you must specify the full filter syntax delimited by a | character, such as filter=key|!=|value.

You can enter multiple filters in a URL. For example, ?filter-status=error&filter-status=warning produces 2 filters for the status column in the dataset.

Searching for null values is a useful way to filter data sets. Filtering by a column without a value searches for rows in which the column is null. To negate a null search, you can append the |!= operator. Here are different ways to specify that a column is null or not null, which you can test using the System dataset or a Log Explorer.

Filter

Result

null-filter-BUNDLE_ID

BUNDLE_ID is null

null-filter-BUNDLE_ID%7C%21%3D

BUNDLE_ID is not null

Filters for Explorers and Dataset Pages

Observe’s Explorer pages are useful starting points for unstructured hunting. The following filters work in:

  • Log Explorer

  • Metrics Explorer

  • Trace Explorer

  • Resource Explorer

An Explorer URL is composed this way:

https://${Customer_ID}.observeinc.com/workspace/${INSTANCE_ID}/${Explorer}?datasetId=${DATASET_ID}&${KEY-VALUE_PARAMETER}&${KEY-VALUE_PARAMETER}

For instance, Metrics Explorer can be called with this URL https://${Customer_ID}.observeinc.com/workspace/${INSTANCE_ID}/${Explorer}?datasetId=${DATASET_ID}&metricName=${METRIC_NAME}

Additional parameters can be added to the URL after an & character.

For example, the URL "https://${Customer_ID}.observeinc.com/workspace/${INSTANCE_ID}/metric-explorer?datasetId=${DATASET_ID}&metricName=node_filesystem_avail_bytes&time-preset=PAST_15_MINUTES" opens the Metrics Explorer to a dataset in your instance containing Node exporter metrics for filesystem available bytes, with a preset time filter of 15 minutes from now.

These filters also work when calling a Dataset page, as in the previous example using the System dataset.

For instance if you want to add a filter for column “OBSERVATION_KIND” and value “system” to the System Dataset query, use "https://${Customer_ID}.observeinc.com/workspace/${INSTANCE_ID}/dataset/event/System-${Object_ID}?time-end=1683675692262&time-start=1683561222716&filter-OBSERVATION_KIND=system".

Filters for Dashboards

Filterable Datasets allow you to customize Dashboard views using Dataset filters. An Observe Dashboard that uses the Filterable Dataset option can be filtered using URL Parameters as well. URL Parameters for these closely resemble URL parameters for regular dataset filters. Instead of using filter, you can use filterds-<datasetId> to target a filterable dataset on a Dashboard.

Parameter

Description

filterds-<datasetid>-<columnId>

Column is null

null-filterds-<datasetid>-<columnId>

Column is null

filterds-<datasetid>-<columnId>|operator|value

Column matches values

null-filterds-<datasetid>-<columnId>|!=

Column is not null

Other Parameters for Explorers

Object names, IDs, and parameters can differ between object types. Check the URLs displayed by the browser when you use the Observe interface to verify that options you want to use will work for the use case.

Explorers support these parameters:

Parameter

Description

DatasetID

filter the Explorer to a dataset

RelatedResourceDatasetID

filter the Explorer dataset picker to datasets related to a Resource dataset

Using OPAL in URL Parameters

While filters are very powerful, some use cases might require a full OPAL statement. Log Explorer, Metrics Explorer, Resource Explorer, and Worksheets support using an OPAL statement:

Parameter

Description

opal

filter the results with an OPAL statement

Note

When using an OPAL statement to filter, you must URL encode the string. For example:

OPAL Editor

// with a comment first

filter is_null(log)

URL Parameter

?opal=%2F%2F+with+a+comment+first%0A%0Afilter+is_null%28log%29

Controlling Dashboard and Worksheet Parameters

Dashboards and Worksheets can use Parameters to filter their display. For instance, the author of a metrics dashboard might connect their list of customer accounts to a dropdown so that troubleshooting users can select from existing accounts instead of using a filter bar.

The configured parameters in a Dashboard or Worksheet can be controlled using URL Parameters.

The author of the dashboard configures these parameters and may have one of the following types:

  • Text

  • Dropdown

  • Number

  • Resource Instance

Text, dropdown, and number values pass as written. For Resource instances, the URL accepts a custom serialization format.

Parameter

Value

Description

param-<key>

a value

One or more global search strings (multiple strings may be passed, for example, search=log&search=error

param-<key>

resourceLabel~primaryKeyName~primaryKeyValue

Sets the value of a resource instance parameter to the following Resource ID: { label: resourceLabel, primaryKeys: [{ name: "primaryKeyName", value: "primaryKeyValue"}] }

For example, use ?param-stringParam=value for a simple parameter, and ?param-key=DiskPressure-ip-172-31-46-130-b3487a97-46d6-45c8-8b98-f67669391713~clusterUid~b3487a97-46d6-45c8-8b98-f67669391713~name~ip-172-31-46-130~type~DiskPressure for a resource parameter.

Resource Parameter Serialization Rules

  • If you open a Resource Instance, you see in the URL resource/<datasetId>~<label>~<...primaryKeyValues> where ...primaryKeyValues is an enumeration for every key~value in the primaryKeys list for the resource. The order of the key/value pairs is not important.

  • You can use <label>~<...primaryKeyValues> as a value for a Resource Instance parameter. You should not specify the Dataset ID as the parameter defines it.

  • You may omit the label, but you must pass ~ as your first character in the sequence because you have omitted the label. For example, ?~<...primaryKeyValues>~ would be the correct syntax in this case.

  • You must escape ~ and \ in labels and primary keys with \(backslash).

    • Because of the nature of this custom serialization format, labels and primary key names or values that contain the character ~ or \ must be encoded by prefixing with \. For example, if you have a label such as Some~label, this must be passed as Some\~label so that it does not split incorrectly during deserialization. Similarly, if you have a label such as Some\label, this must be passed as Some\\label as \ is an escape character in this serialization format, so must be un-escaped to be parsed correctly. The same escaping needs to be applied to the names and values of the primary keys, as well.

Controlling Dataset Pages

In addition to Filters, Dataset and Resource Instance pages have two parameters that can be useful to control via URL Parameters. Dataset and Resource Instance pages have Tabs, such as Dashboards, Resources, Logs & Events, and Related. The tab can be selected via URL Parameter:

Tab

Parameter

Dashboards

Not needed

Resources

?v-tab=resources

Logs & Events

?v-tab=Logs%20%26%20Events

Related

?v-tab=related

The Dashboards tab of a Dataset or Resource Instance page can show any existing Dashboard related to the Dataset or Resource Instance, and will have a default set by the page. However, a URL Parameter can be used to override this default and set a specific dashboard:

Parameter

?v-dash=${DASHBOARD_ID}

Note

The dashboard ID must refer to a dashboard that is recognized as relevant to the Dataset or Resource Instance.