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 |
---|---|
|
Accepts a timestamp or an ISO time. |
|
Accepts a timestamp or an ISO time. |
|
Accepts a preset key. |
Example Date and Time Formats
Formats |
Description |
---|---|
|
UNIX timestamp in milliseconds |
|
An ISO string with a timezone offset specified |
|
An ISO string specified in UTC time |
|
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 |
---|---|---|
|
Value |
|
|
|
|
|
|
|
|
|
|
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 |
---|---|---|
|
Value |
is equal to |
|
|
|
|
|
|
|
|
|
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 |
---|---|---|
|
|
One or more global search strings (multiple strings may be passed, for example, |
|
|
Sets the value of a resource instance parameter to the following Resource ID: |
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 everykey~value
in theprimaryKeys
list for the resource. The order of thekey/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 asSome~label
, this must be passed asSome\~label
so that it does not split incorrectly during deserialization. Similarly, if you have a label such asSome\label
, this must be passed asSome\\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.
The Explore Page with Filter and Search¶
On the Explore page, you can also control the Filter and Search settings of the Filter bar at the top of the page.
Parameter |
Value |
Description |
---|---|---|
|
|
Sets the value of the parameter with ID “key” to “a value” |
|
|
Similar to |
|
Encoded JSON |
The URL differs slightly from using filters on other pages. It requires |
Filters and Apps¶
On the Apps page, you may control a single search for the table using the search
parameter.
Parameter |
Value |
Description |
---|---|---|
|
|
One |
View State¶
Parameter |
Description |
---|---|
|
selected dashboard (Dataset and Resource Instance Pages) |
|
selected tab (Dataset and Resource Instance Pages) |