URL Query Parameters

Overview

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.

Example Format

https://${Customer_ID}.observeinc.com/workspace/12345678/resource/41950995~tinyk8s-ops~uid~575ffab0-1850-4505-b41d-bee84b3b310c?time-end=1683575622716&time-start=1683561222716

For example, the URL "https://${Customer_ID}.observeinc.com/workspace/12345678/dataset/event/Device-Events-98765432?s=2713-yc1s7omo" links to a Dataset in your instance. If you want to add a filter parameter with key “fig” and the value “bar” with the operator “=” to the URL, use the parameter, ?filter-fig=bar.

You can add links in your application to your Observe instance. For instance, you may want to link to a Dashboard that you access frequently without logging into Observe and locating 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 to URI-Component encode 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, URI-encode query string parameter keys and values.

Observe generates URLs with parameters matching your current view in Observe. URLs generated by Observe contain proper URI encoding in them.

The following tables list the currently supported URL Parameters:

Time Ranges

Parameter

Description

"time-start": "2023-03-08T16%3A54%3A05.268Z",

Accepts a timestamp or an ISO time.

"time-end": "2023-03-08T16%3A54%3A05.268Z",

Accepts a timestamp or an ISO time.

"time-preset": "preset_key",

Accepts a preset key.

Example Date and Time Formats

Formats

Description

?time-start=1686165391864

UNIX timestamp in milliseconds

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

An ISO string with a timezone offset specified

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

An ISO string specified in UTC time

?time-start=2023-06-07T15.02.31-04.00

A custom ISO format for URL readability

Note

When passing an ISO string containing precision to seconds, not milliseconds, you may replace the : with . in the URL for an easier-to-read format. The . does not have to be URI encoded.

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_24_HOURS

  • PAST_7_DAYS

  • PAST_30_DAYS

Filters for Dataset Pages

For Event and Resource Datasets, you can control filters for these pages using URL parameters. You can enter duplicate filters for multiple values. For example, ?filter-status=error&filter-status=warning produces 2 filters for the status column in the dataset.

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.

If you omit the value, Observe assumes an empty string. To specify the value as null, you need to prefix your URL parameter with null-. For the shorthand version, this becomes null-filter-<key>, and for the long form, it becomes null-filter=key|!= for key != null.

Parameter

Value

Description

filter-<columnId>

Value

columnId = value

filter

columnId|operator|value

columnId operator value

null-filter-<columnId>

columnId = null

null-filter

columnId|operator

columnId operator

Use the following operators for non-shorthand syntax:

Operator

Description

=

Equal

!=

Not Equal

>

Greater than

<

Less than

>=

Greater than or Equal to

<=

Less than or Equal to

~

Contains

!~

Does Not Contain

Filters for Filtered Datasets in Dashboards

Filterable Datasets allow you to customize Dashboard views using Dataset filters. 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

Value

Description

filterds-<datasetid>-<columnId>

Value

is equal to value. Allows you to specify the columnId in the parameter name.

filterds-<datasetid>

columnId|operator|value

columnId operator value

null-filterds-<datasetid>-<columnId>

columnId = null

null-filterds-<datasetid>

columnId|operator

columnId operator null

Parameters for Dashboards and Worksheets

You can also configure parameters for Dashboards and Worksheets 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.

Filters and Apps

On the Apps page, you may control a single search for the table using the search parameter.

Parameter

Value

Description

search

string

One search string can be passed.

View State

Parameter

Description

"v-dash": "id",

selected dashboard (Dataset and Resource Instance Pages)

"v-tab": "tab",

selected tab (Dataset and Resource Instance Pages)