mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 17:28:26 -04:00
docs: [APM] custom links (#60595)
This commit is contained in:
Brandon Morelli
GitHub
parent
f462b10863
commit
df9f2ac577
5 changed files with 220 additions and 0 deletions
218
docs/apm/custom-links.asciidoc
Normal file
218
docs/apm/custom-links.asciidoc
Normal file
|
|
@ -0,0 +1,218 @@
|
|||
[[custom-links]]
|
||||
=== Custom links
|
||||
|
||||
Elastic's custom link feature allows you to easily create up to 500 dynamic links
|
||||
based on your specific APM data.
|
||||
Custom links can be filtered to only appear in the APM app for relevant services,
|
||||
environments, transaction types, or transaction names.
|
||||
|
||||
Ready to dive in? Jump straight to the <<custom-links-examples,examples>>.
|
||||
|
||||
[float]
|
||||
[[custom-links-create]]
|
||||
=== Create a link
|
||||
|
||||
Each custom link consists of a label, url, and optional filter.
|
||||
The easiest way to create a custom link is from within the actions dropdown in the transaction detail page.
|
||||
This method will automatically apply filters, scoping the link to that specific service,
|
||||
environment, transaction type, and transaction name.
|
||||
|
||||
Alternatively, you can create a custom link in the APM app by navigating to **Settings** > **Customize UI**,
|
||||
and selecting **Create custom link**.
|
||||
|
||||
[float]
|
||||
[[custom-links-label]]
|
||||
==== Label
|
||||
|
||||
The name of your custom link.
|
||||
This text will be shown in the actions context menu,
|
||||
so keep it as short as possible.
|
||||
|
||||
TIP: Custom links are displayed alphabetically in the actions menu.
|
||||
|
||||
[float]
|
||||
[[custom-links-url]]
|
||||
==== URL
|
||||
|
||||
The URL your link points to.
|
||||
URLs support dynamic field name variables, encapsulated in double curly brackets: `{{field.name}}`.
|
||||
These variables will be replaced with transaction metadata when the link is clicked.
|
||||
|
||||
Because everyone's data is different,
|
||||
you'll need to examine your own traces to see what metadata is available for use.
|
||||
The easiest way to do this is to select a trace in the APM app, and click **Metadata** in the **Trace Sample** table.
|
||||
|
||||
[role="screenshot"]
|
||||
image::apm/images/example-metadata.png[Example metadata]
|
||||
|
||||
[float]
|
||||
[[custom-links-filters]]
|
||||
==== Filters
|
||||
|
||||
Filter each link to only appear so it only appears for specific services or transactions.
|
||||
You can filter on the following fields:
|
||||
|
||||
* `service.name`
|
||||
* `service.env`
|
||||
* `transaction.type`
|
||||
* `transaction.name`
|
||||
|
||||
Multiple values are allowed when comma separated.
|
||||
|
||||
[float]
|
||||
[[custom-links-examples]]
|
||||
=== Custom link examples
|
||||
|
||||
// Relevant documentation links
|
||||
:jira-query-params: https://confluence.atlassian.com/jirakb/how-to-create-issues-using-direct-html-links-in-jira-server-159474.html
|
||||
:github-query-params: https://help.github.com/en/github/managing-your-work-on-github/about-automation-for-issues-and-pull-requests-with-query-parameters
|
||||
|
||||
Not sure where to start with custom links?
|
||||
Take a look at the examples below, and customize them to your liking!
|
||||
|
||||
[float]
|
||||
[[custom-links-examples-email]]
|
||||
==== Email
|
||||
|
||||
Email the owner of a service.
|
||||
|
||||
|====
|
||||
|Label |`Email <SERVICE_NAME> engineer`
|
||||
|Link |`mailto:<TEAM_OR_ENGINEER>@<COMPANY_NAME>.com`
|
||||
|Filters |`service.name:<SERVICE_NAME>`
|
||||
|====
|
||||
|
||||
**Example**
|
||||
|
||||
This link opens an email addressed to the team or owner of `python-backend`.
|
||||
It will only appear on services with the name `python-backend`.
|
||||
|
||||
|====
|
||||
|Label |`Email python-backend engineers`
|
||||
|Link |`mailto:python_team@elastic.co`
|
||||
|Filters |`service.name:python-backend`
|
||||
|====
|
||||
|
||||
[float]
|
||||
[[custom-links-examples-gh]]
|
||||
==== GitHub issue
|
||||
|
||||
Open a GitHub issue with pre-populated metadata from the selected trace sample.
|
||||
|
||||
|====
|
||||
|Label |`Open an issue in <REPO_NAME>`
|
||||
|Link |`https://github.com/<ORG>/<REPO>/issues/new?title=<TITLE>&body=<BODY>`
|
||||
|Filters |`service.name:client`
|
||||
|====
|
||||
|
||||
**Example**
|
||||
|
||||
This link opens a new GitHub issue in the apm-agent-rum repository.
|
||||
It populates the issue body with relevant metadata from the currently active trace.
|
||||
Clicking this link results in the following issue being created:
|
||||
|
||||
[role="screenshot"]
|
||||
image::apm/images/create-github-issue.png[Example github issue]
|
||||
|
||||
|====
|
||||
|Label |`Open an issue in apm-rum-js`
|
||||
|Link |`https://github.com/elastic/apm-agent-rum-js/issues/new?title=Investigate+APM+trace&body=Investigate+the+following+APM+trace%3A%0D%0A%0D%0Aservice.name%3A+{{service.name}}%0D%0Atransaction.id%3A+{{transaction.id}}%0D%0Acontainer.id%3A+{{container.id}}%0D%0Aurl.full%3A+{{url.full}}`
|
||||
|Filters |`service.name:client`
|
||||
|====
|
||||
|
||||
See the {github-query-params}[GitHub automation documentation] for a full list of supported query parameters.
|
||||
|
||||
[float]
|
||||
[[custom-links-examples-jira]]
|
||||
==== Jira task
|
||||
|
||||
Create a Jira task with pre-populated metadata from the selected trace sample.
|
||||
|
||||
|====
|
||||
|Label |`Open an issue in Jira`
|
||||
|Link |`https://<JIRA_BASE_URL>/secure/CreateIssueDetails!init.jspa?<ARGUMENTS>`
|
||||
|====
|
||||
|
||||
**Example**
|
||||
|
||||
This link creates a new task on the Engineering board in Jira.
|
||||
It populates the issue body with relevant metadata from the currently active trace.
|
||||
Clicking this link results in the following task being created in Jira:
|
||||
|
||||
[role="screenshot"]
|
||||
image::apm/images/create-jira-issue.png[Example jira issue]
|
||||
|
||||
|====
|
||||
|Label |`Open a task in Jira`
|
||||
|Link |`https://test-site-33.atlassian.net/secure/CreateIssueDetails!init.jspa?pid=10000&issuetype=10001&summary=Created+via+APM&description=Investigate+the+following+APM+trace%3A%0D%0A%0D%0Aservice.name%3A+{{service.name}}%0D%0Atransaction.id%3A+{{transaction.id}}%0D%0Acontainer.id%3A+{{container.id}}%0D%0Aurl.full%3A+{{url.full}}`
|
||||
|====
|
||||
|
||||
See the {jira-query-params}[Jira application administration knowledge base]
|
||||
for a full list of supported query parameters.
|
||||
|
||||
[float]
|
||||
[[custom-links-examples-kib]]
|
||||
==== Kibana dashboards
|
||||
|
||||
Link to a custom dashboard in Kibana.
|
||||
|
||||
|====
|
||||
|Label |`Open transaction in custom visualization`
|
||||
|Link |`https://kibana-instance/app/kibana#/dashboard?_g=query:(language:kuery,query:'transaction.id:{{transaction.id}}'...`
|
||||
|====
|
||||
|
||||
**Example**
|
||||
|
||||
This link opens the current `transaction.id` in a custom kibana dashboard.
|
||||
There are no filters set.
|
||||
|
||||
|====
|
||||
|Label |`Open transaction in Python drilldown viz`
|
||||
|URL |`https://kibana-instance/app/kibana#/dashboard?_g=(filters:!(),refreshInterval:(pause:!t,value:0),time:(from:now-24h,to:now))&_a=(description:'',filters:!(),fullScreenMode:!f,options:(hidePanelTitles:!f,useMargins:!t),panels:!((embeddableConfig:(),gridData:(h:15,i:cb79c1c0-1af8-472c-aaf7-d158a76946fb,w:24,x:0,y:0),id:c8c74b20-6a30-11ea-92ab-b5d3feff11df,panelIndex:cb79c1c0-1af8-472c-aaf7-d158a76946fb,type:visualization,version:'7.7')),query:(language:kuery,query:'transaction.id:{{transaction.id}}'),timeRestore:!f,title:'',viewMode:edit)`
|
||||
|====
|
||||
|
||||
[float]
|
||||
[[custom-links-examples-slack]]
|
||||
==== Slack channel
|
||||
|
||||
Open a specified slack channel.
|
||||
|
||||
|====
|
||||
|Label |`Open SLACK_CHANNEL`
|
||||
|Link |`https://COMPANY_SLACK.slack.com/archives/SLACK_CHANNEL`
|
||||
|Filters |`service.name` : `SERVICE_NAME`
|
||||
|====
|
||||
|
||||
**Example**
|
||||
|
||||
This link opens a company slack channel, #apm-support.
|
||||
It only appears when `transaction.name` is `GET user/login`.
|
||||
|
||||
|====
|
||||
|Label |`Open #apm-user-support`
|
||||
|Link |`https://microsoft.slack.com/archives/efk52kt23k`
|
||||
|Filters |`transaction.name:GET user/login`
|
||||
|====
|
||||
|
||||
[float]
|
||||
[[custom-links-examples-web]]
|
||||
==== Website
|
||||
|
||||
Open an internal or external website.
|
||||
|
||||
|====
|
||||
|Label |`Open <WEBSITE>`
|
||||
|Link |`https://<COMPANY_SLACK>.slack.com/archives/<SLACK_CHANNEL>`
|
||||
|Filters |`service.name:<SERVICE_NAME>`
|
||||
|====
|
||||
|
||||
**Example**
|
||||
|
||||
This link opens more data on a specific `user.email`.
|
||||
It only appears on front-end transactions.
|
||||
|
||||
|====
|
||||
|Label |`View user internally`
|
||||
|Link |`https://internal-site.company.com/user/{{user.email}}`
|
||||
|Filters |`service.name:client`
|
||||
|====
|
||||
BIN
docs/apm/images/create-github-issue.png
Normal file
BIN
docs/apm/images/create-github-issue.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 144 KiB |
BIN
docs/apm/images/create-jira-issue.png
Normal file
BIN
docs/apm/images/create-jira-issue.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 178 KiB |
BIN
docs/apm/images/example-metadata.png
Normal file
BIN
docs/apm/images/example-metadata.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 249 KiB |
|
|
@ -37,6 +37,8 @@ include::metrics.asciidoc[]
|
|||
|
||||
include::agent-configuration.asciidoc[]
|
||||
|
||||
include::custom-links.asciidoc[]
|
||||
|
||||
include::advanced-queries.asciidoc[]
|
||||
|
||||
include::settings.asciidoc[]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue