Document URL Parameters

[justenwalker]

The format of the URL parameters is RISON, but there is no documentation around the structure of this object. It doesn't appear to be a raw ES query object converted from JSON to RISON. Aside from reverse-engineering by reading the source code - there should be some documentation about the structure of the objects passed so that URLs can be easily generated by external systems.

Example use-case

1. ELK is aggregating log information to a central place.
2. An error occurs on an application server.
3. An email is sent with the corresponding Kibana Discover URL which narrows down the time-frame and applies some filters.
4. An engineer clicks on the URL and is able to quickly get the log information they need to debug issue.

[webmstr]

+1. I wanted use a link with filters, but the syntax was just to alien.

[ljcastro]

+1 I am integrating dashboards and discover in Tableau and I need more documentation about the parameters in URL. Thanks

[konste]

+1 Need to be able to generate those URLs programmatically, based on some parameters.

[thehybridtechnician]

+1 Any documentation would be a great benefit.

[bradvido]

+1. I was able to reverse engineer some of it from looking at the source, but it's still a bit confusing!

[ghirardinicola]

+1

[Heliosmaster]

+1

[elvarb]

I'm using something similiar with Kibana3, but more features and options would be very welcome.

1. Create a few dashboards where a part of the name is an object in certain events.
2. When one of those events come in send an email with few details and a link to Kibana where the Dashboard URL is specified using the object from the event.

[kmoe]

+1
see https://discuss.elastic.co/t/kibana-4-and-5-sensible-url-parameters/40145

[Portree-Kid]

+1

[simianhacker]

My guess is that we are not going to do this any time soon because we have to come up with a workable solution for the whole IE11 URL length thing (#6531). Which means that RISON stuff might disappear or we will replace it with some other mechanism which allows us to override stuff from the URL via args. At that time we will be sure to document it.

[GrahamHannington]

In my experience, when setting the absolute from and to date-time values in its URL query string, Kibana always uses UTC, marked by a Z zone designator. For example:

?_g=(time:(from:'2016-11-06T18:36:40.658Z',to:'2016-11-07T05:29:33.239Z'))

This might be very old news to some readers: if you roll your own URL, you can specify from and to values with other zone designators. For example, if you specify:

?_g=(time:(from:'2016-11-05T18:36:40.658%2B08:00',to:'2016-11-08T05:29:33.239%2B08:00'))

then Kibana (here, I'm using 5.0) replaces the URL with equivalent Z-zoned values:

... from:'2016-11-05T10:36:40.658Z' ... to:'2016-11-07T21:29:33.239Z' ... 

If your zone designator uses a plus (+) sign, you must URL-encode it (as %2B). If you don't, you won't get the desired result. For example, if you specify:

?_g=(time:(from:'2016-11-05T18:36:40.658+08:00',to:'2016-11-08T05:29:33.239+08:00'))

then Kibana (at least, in Google Chrome, if the browser makes a difference here) replaces those values with:

... from:'2016-11-05T18:36:40.658%2008:00' ... to:'2016-11-08T05:29:33.239%2008:00' ...

Kibana developers: at your discretion, you might choose to trap this. Or leave it as is: "user beware" ("meddle with Kibana URLs at your peril")?

Some readers might find some of the above useful in the documentation requested/proposed by this issue.

[tishion]

Is this issue solved?
actually we just need an approach to pass the index name in the URL query.

[devinbfergy]

+1

[devinbfergy]

I want to be able to link machine learning to discover based on the ml results.

[hstern]

+1 4 years for a documentation request is a very long time.

[narcher7]

@bmorelli25: Was this issue completed by your #104 documentation tasks?

[bmorelli25]

No. Marjorie referenced this issue by mistake.

[elasticmachine]

Pinging @elastic/kibana-app-arch (Team:AppArch)

[lukeelmers]

To provide a bit of context: one of the reasons these parameters have remained undocumented is because our approach to state management has been changing as we work on migrating core Kibana applications to the new platform.

As part of this effort, the source of truth for global state is shifting away from URLs and into the individual plugin APIs themselves. URL state management then becomes an implementation detail of individual applications, rather than existing as a global concept across Kibana. More details on the thinking behind this can be found in #39855.

The implication here is that each application (Discover, Dashboard, etc) will ultimately determine whether to store state in the URL, and if so, whether to document this state as a public part of their plugin's API. As these apps get closer to completing the migration, we expect some of these longer-term contracts to be identified (and documented 🙂).

Also worth mentioning - the idea of a direct access link service has been brought up in the past, which is something that has potential to address some of the use cases discussed here. Feel free to follow along on that issue if it is a topic of interest to you.

[justenwalker]

It's been quite a long time since I had initially brought up this issue (over 4 years!). I appreciate the follow up. I'm not currently using Kibana at $job, but it's always nice to see some movement on this every now and again 😄

I took a look at the direct access link service and, while that's a cool and useful idea, it does require access to the Kibana API; which is a dependency that I wouldn't want to rely on when an exceptions/errors are happening in my service. Also, it would not be possible if my services were isolated from Kibana.

This issue recommends documenting the URL scheme to provide a contract with users of Kibana so that they can reliably assemble links to those queries without depending on access to an API. If providing such a contract is a no-go, perhaps the use-case can still be served some other way?

---

Although this is out of scope of this issue, Here is my suggestion (assuming it does not already exist):

1. Add the ability to define named parameterized queries using the API or UI; Think "Stored procedures". (http://localhost:5601/query_by_name/logs_by_request_id)
2. Ensure that links to these parameterized queries can be made by providing those parameters in the URL. (http://localhost:5601/query_by_name/logs_by_request_id?env=production&request_id=foo)

This has the advantage of not requiring any access to the API to create these links and pushes the definition of that parameter contract to the end-user; freeing Elastic from the responsibility of maintaining such a contract. Perhaps this could even be an extension of the direct link access service?

[lukeelmers]

@justenwalker Sorry for the delay, and thanks for your note. The "stored procedures" idea is an interesting one; I'm reposting it over in #25247 for any further discussion.

I had also brought up the idea of a client-side "redirect app" which could solve the problem of an environment that's isolated from Kibana. Basically an app which proxies a predefined state object to a destination app without needing to worry about whether that app happens to store state in the URL. e.g. localhost:5601/app/goto/dashboard/someId?_=${encodedStateObject}.

In terms of the original concern raised here, I think my previous comment is the best summary of the current status on this issue for the time being:

...each application (Discover, Dashboard, etc) will ultimately determine whether to store state in the URL, and if so, whether to document this state as a public part of their plugin's API. As these apps get closer to completing the migration, we expect some of these longer-term contracts to be identified (and documented 🙂).

Having apps get to the place of identifying an interface for their public state will be a prerequisite to writing up detailed documentation. This is in discussion right now, but involves a lot of moving pieces and coordination among various teams working on Kibana.

Ideally apps will begin formalizing their state with TS interfaces, which would at least be a step in the right direction in the interim. I'll avoid diverting too much further off-topic, but expect to hear more on that over in #25247 as well.

[ppisljar]

Thank you for contributing to this issue, however, we are closing this issue due to inactivity as part of a backlog grooming effort. If you believe this feature/bug should still be considered, please reopen with a comment.