Skip to content

Commit

Permalink
Merge branch 'master' into dev/drilldowns/changes-to-dashboard-link-g…
Browse files Browse the repository at this point in the history
…enerator
  • Loading branch information
elasticmachine authored Mar 30, 2020
2 parents 0d6289e + 2565084 commit 0c9a324
Show file tree
Hide file tree
Showing 885 changed files with 22,720 additions and 8,916 deletions.
1 change: 1 addition & 0 deletions .eslintrc.js
Original file line number Diff line number Diff line change
Expand Up @@ -491,6 +491,7 @@ module.exports = {
'x-pack/dev-tools/mocha/setup_mocha.js',
'x-pack/scripts/*.js',
],
excludedFiles: ['**/integration_tests/**/*'],
rules: {
'import/no-commonjs': 'off',
'prefer-object-spread/prefer-object-spread': 'off',
Expand Down
1 change: 1 addition & 0 deletions .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,7 @@
/src/legacy/server/saved_objects/ @elastic/kibana-platform
/src/legacy/server/status/ @elastic/kibana-platform
/src/plugins/status_page/ @elastic/kibana-platform
/src/plugins/saved_objects_management/ @elastic/kibana-platform
/src/dev/run_check_published_api_changes.ts @elastic/kibana-platform

# Security
Expand Down
6 changes: 2 additions & 4 deletions .i18nrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
"newsfeed": "src/plugins/newsfeed",
"regionMap": "src/legacy/core_plugins/region_map",
"savedObjects": "src/plugins/saved_objects",
"savedObjectsManagement": "src/plugins/saved_objects_management",
"server": "src/legacy/server",
"statusPage": "src/legacy/core_plugins/status_page",
"telemetry": [
Expand All @@ -51,10 +52,7 @@
"visTypeVega": "src/legacy/core_plugins/vis_type_vega",
"visTypeVislib": "src/legacy/core_plugins/vis_type_vislib",
"visTypeXy": "src/legacy/core_plugins/vis_type_xy",
"visualizations": [
"src/plugins/visualizations",
"src/legacy/core_plugins/visualizations"
]
"visualizations": "src/plugins/visualizations"
},
"exclude": [
"src/legacy/ui/ui_render/ui_render_mixin.js"
Expand Down
218 changes: 218 additions & 0 deletions docs/apm/custom-links.asciidoc
Original file line number Diff line number Diff line change
@@ -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`
|====
Binary file added docs/apm/images/create-github-issue.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/apm/images/create-jira-issue.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/apm/images/example-metadata.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 2 additions & 0 deletions docs/apm/using-the-apm-ui.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ include::metrics.asciidoc[]

include::agent-configuration.asciidoc[]

include::custom-links.asciidoc[]

include::advanced-queries.asciidoc[]

include::settings.asciidoc[]
Expand Down
Loading

0 comments on commit 0c9a324

Please sign in to comment.