Services

Create a custom service rule

1. From the sidebar, click Applications and select the Services tab.
2. Click Configure Services
3. Click Add Custom Service Rule
4. From the drop-down list, select the tags.

One reason for using a custom service rule is to use existing meta information of your infrastructure components. For example, if you label your Docker containers with domain-specific information, such as com.acme.service-name:myservice, to map services from this label select the docker.label and com.acme.service-name tags. All calls that pass a container with the label com.acme.service-name are associated with a service, which is named by that value, for example, myservice. There are multiple tags available to create custom service mapping.

You can also add multiple keys for service mapping. Multiple tags are concatenated with a dash. Note all keys need to match, For example, if you want to separate your staging services based on the host zone you can add two keys: host.zone + docker.label:com.acme.service-name. Your services would then be named with a concatenation of the values for the host zone followed by the docker label. That way you would separate out the two services for example prod-myservice and dev-myservice.

By using a special tag service.default_name, a custom service rule can also be used to extend service default rules with more tags. For example, to split the automatically created services by host zones, create the custom service rule by using the tags service.default_name and host.zone.

Setting the service name globally

You can set a service name for all the calls associated with a service. The service name can be set only for the processes that are monitored by an Instana tracer.

To set the service name for all the incoming and outgoing calls from a service, set the INSTANA_SERVICE_NAME environment variable on the process.

When you set the service name, the name of the process is not changed. To rename the process, use the INSTANA_PROCESS_NAME environment variable.

You can set a global service name for the following tracers by using the configuration in code:

• Go
• Node.js
• PHP
• Haskell

For more information about the environment variables recognized by Instana, see Environment Variables.

Setting the service name per call

You can set a service name for every call. When you change the service name for a call, the source or destination service of the target entry or exit span is changed.

To change the service name for a call, add a custom tag (custom.tags.service) to the target span. Choose one of the following target tracer SDKs:

• Java
• .NET
• Python
• Ruby
• PHP
• Go
• Node.js
• Haskell

Setting the service name in OpenTelemetry or OpenTracing

To set a service name in OpenTelemtry or OpenTracing, use the function setTag.

Example: span.setTag('service', 'my-service')

OpenTracing is archived, use OpenTelemetry instead.

Specify the X-Instana-Service HTTP header

By setting the X-Instana-Service HTTP header on a call, the destination (the service, which receives the HTTP request) is tagged with the value that is provided in the header.

Note: The X-Instana-Service HTTP header is not automatically collected. For it to work, the Instana agent must be configured , see "Capturing custom HTTP headers".

Map to unmonitored service with custom name

Calls to a service not monitored by Instana are mapped to a service by using call tags.

For example, HTTP calls to a third-party API such as www.google.com are mapped to service www.google.com based on the HTTP host header (call.http.host tag). Calls to www.google.fr or www.google.de are mapped to different services because the HTTP host headers are different.

You can map all the calls to different domains to a service named "Google" by adding the following manual service configuration:

{
    "tagFilterExpression": {
        "type": "TAG_FILTER",
        "name": "call.http.host",
        "value": "www.google.",
        "operator": "STARTS_WITH",
        "entity": "NOT_APPLICABLE"
    },
    "unmonitoredServiceName": "Google",
    "description": "Map calls to different google domains to Google service",
    "enabled": true
}

Link calls to an existing database or messaging service that is created from a monitored infrastructure entity

If a database or a messaging system is monitored by Instana, calls to that database or messaging system should be mapped to a service based on the infrastructure tag (e.g. MySQL@3306 on demo-host) thanks to infrastructure correlation. But sometimes due to the presence of a proxy or a load balancer, the infrastructure correlation may not work because Instana does not monitor or instrument that component and does not know how requests are routed. In consequence, calls will be mapped to a service based on the call tags (e.g. call.database.schema, call.database.connection or call.messaging.address) as if the destination service is not monitored.

In this case, you will find another service created from the infrastructure entity with no calls. You can use the following manual service configuration to map calls to that existing service:

{
    "tagFilterExpression": {
        "type": "TAG_FILTER",
        "name": "call.database.connection",
        "value": "jdbc:mysql://10.128.0.1:3306",
        "operator": "CONTAINS",
        "entity": "NOT_APPLICABLE"
    },
    "existingServiceId": "a880d1875389b78b49b19387ef7ab815b313764f", // service id of "MySQL@3306 on demo-host" service, can be found in the "serviceId" url parameter of the service dashboard
    "description": "Link calls to MySQL@3306 on demo-host service",
    "enabled": true
}

Service flow map limitation

The service flow map shows accurate data currently only for short running synchronous traces that finish within 20 seconds. In every other case, the service flow map might show inaccurate data.

Why am I not seeing any services listed?

The reason no services are listed is due to either the agent not running in APM mode, having no agent installed; therefore, no traces were collected, or if you have an agent installed, traces were not collected during your selected timeframe.

To check whether an agent is installed and running, click Infrastructure to view any hosts on the infrastructure map that may have an agent, or click More > Agents to see a list of installed agents. If there are no agents listed, see the documentation on how to install an agent or create an application perspective.

Why does the service name sometimes change?

The service mapping relies on infrastructure data. However, in some scenarios, the trace data cannot be enriched with infrastructure data. For example, trace data might not be enriched shortly after an Instana agent, or a monitored process was started. It takes some time until the monitored application gets fully instrumented and until tracers and sensors start collecting data. If the first few traces are collected before all sensors become active, these traces might be missing some or even all infrastructure data. In such cases, the service name used is less specific; for example, HTTP host rather than SpringBoot application name.

A mechanism known as resilient mapping is used to avoid service-mapping issues that are related to restarts of Instana agents or monitored processes. Resilient mapping takes effect if the infrastructure data for mapping calls to the correct service is unavailable. The resilient mapping can assign a call to the right service by using a cache of previous mapping results. However, this can lead to an unexpected service name, for example, if the cache contains infrastructure data that is outdated. The expected service comes back automatically when the resilient cache is updated.