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.

Format 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 following URL links to the System event dataset in your instance with an end time of Tuesday, May 9, 2023 23:41:32.262 UTC:

https://${Customer_ID}.observeinc.com/workspace/${INSTANCE_ID}/dataset/event/System-${Object_ID}?time-end=1683675692262

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

For example, the following URL 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:

https://${Customer_ID}.observeinc.com/workspace/${INSTANCE_ID}/dataset/event/System-${Object_ID}?time-end=1683675692262\&time-start=1683561222716

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](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.

Use time ranges as URL query parameters

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 colon (:) with a dot (.) in the URL for an easier-to-read format. The dot (.) 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 dot (.) 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

Use filters as URL query parameters

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 the following parts:

The key, or column that you want to test
The operator
The value

Filter keys can be an ID such as filter-attributes or a JSON path such as filter-attributes.debug_source.

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 pipe (|) 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 as follows:

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 the following 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 following URL 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:

https://${Customer_ID}.observeinc.com/workspace/${INSTANCE_ID}/metric-explorer?datasetId=${DATASET_ID}&metricName=node_filesystem_avail_bytes&time-preset=PAST_15_MINUTES

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 the following URL:

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 the following parameters:

Parameter	Description
DatasetID	Filter the Explorer to a dataset.
RelatedResourceDatasetID	Filter the Explorer dataset picker to datasets related to a Resource dataset.

Use OPAL as URL query parameters

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

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

OPAL Editor

// with a comment first

filter is_null(log)

The URL parameter:

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

Control 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"}] }`

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.
Use ?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. Do 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>~ is the correct syntax in this case.
You must escape ~ and \ in labels and primary keys with a backslash () character.

Because of the nature of this custom serialization format, labels and primary key names or values that contain the tilde (~) or backslash () characters 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 the backslash () 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.

Control 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 the following tabs which can be selected via the URL parameter:

Tab	Parameter
Dashboards	None 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:

?v-dash=${DASHBOARD_ID}

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

Use tags as URL query parameters

When you pivot to a dashboard or explorer page from a tag or collection of tags from a separate explorer table, you can switch between related pages that match the same tags.

For example, in one dataset, you might have a column called cluster with the name of the cluster. In a separate dataset, you might have a column called clusterID with the name of the cluster. Both datasets present the same information, but with different column names. You can assign a tag of cluster_name to both columns, and they will be linked across your system, so when you query with the tag of cluster_name you will get both.

Case	Example
Tag key with value	`?tag-k8s.service.name=ingest-auth-proxy`
Tag key with null value	`?tag-k8s.service.name`
Tag key with multiple values	`?tag-k8s.service.name=ingest-auth-proxy,apiserver`
Required tag with optional tags	`?requiredTag-k8s.pod.name=loader-0&tag-k8s.service.name=loader`