Skip to main content

Instana

Reading time: 0 minute(s) (0 words)

Instana is an observability platform that delivers automated Application Performance Monitoring (APM), used for website, infrastructure, and application monitoring.

Scope of support

Currently, the Nobl9 integration with Instana does not support monitoring website metrics and ratio metrics for application metrics.

Authentication

Instana uses an API token for authorization. When setting up the Nobl9 agent or direct connection to your Instana instance, you need to provide an API token.

You can get your Instana API token in two ways:

  • By entering the following URL in your browser:

    https://${BASE_URL}/#/config/team/accessControl/apiTokens

    where the ${BASE_URL} is the URL that points to your Instana instance, for example:

    • for SaaS, https://instance-example.instana.io
    • for self-hosted solutions, http://instana-service:9000
  • In the Instana UI, by selecting Settings > Team Settings > Access Control > API Tokens > Add API Token

For more information on authentication, refer to the Instana API | Instana documentation.

warning

Do not add any additional permissions to the API token. Metrics fetching works well with a clean API token.

Adding Instana as a data source

To ensure data transmission between Nobl9 and your data source, it may be necessary to list Nobl9 IP addresses as trusted.

IP addresses to add to your allowlist:
  • 18.159.114.21
  • 18.158.132.186
  • 3.64.154.26
Applies to app.nobl9.com only. In all other cases, contact Nobl9 support.

You can add the Instana data source using the direct or agent connection methods. For both methods, start with these steps:

  1. Navigate to Integrations > Sources.
  2. Click .
  3. Click the relevant Source icon.
  4. Choose a relevant connection method (Agent or Direct), then configure the source as described below.

Instana direct

Direct configuration in the UI

A direct connection to Instana requires users to enter their credentials, which Nobl9 stores safely. To set up this type of connection:

  1. Select one of the following Release Channels:
    • The stable channel is fully tested by the Nobl9 team. It represents the final product; however, this channel does not contain all the new features of a beta release. Use it to avoid crashes and other limitations.
    • The beta channel is under active development. Here, you can check out new features and improvements without the risk of affecting any viable SLOs. Remember that features in this channel may be subject to change.
  2. Add the URL to connect to your data source (mandatory).
    Provide the base URL that points to your Instana instance. For more details, refer to the Authentication section above.

  3. Enter your Instana API Token (mandatory).
    To use Instana web REST API, you need to create an API token. For more details, refer to the Authentication section above.

  1. Select a Project.
    Specifying a project is helpful when multiple users are spread across multiple teams or projects. When the Project field is left blank, Nobl9 uses the default project.
  2. Enter a Display Name.
    You can enter a user-friendly name with spaces in this field.
  3. Enter a Name.
    The name is mandatory and can only contain lowercase, alphanumeric characters, and dashes (for example, my-project-1). Nobl9 duplicates the display name here, transforming it into the supported format, but you can edit the result.
  4. Enter a Description.
    Here you can add details such as who is responsible for the integration (team/owner) and the purpose of creating it.
  5. Specify the Query delay to set a customized delay for queries when pulling the data from the data source.
    • The default value in Instana integration for Query delay is 1 minute.
    info
    Changing the Query delay may affect your SLI data. For more details, check the Query delay documentation.
  6. Click Add Data Source.

Direct using CLI - YAML

The YAML for setting up a direct connection to Instana looks like this:

apiVersion: n9/v1alpha
kind: Direct
metadata:
name: instana-direct
displayName: Instana Direct
project: default
spec:
description: Direct settings for Instana datasource
sourceOf:
- Metrics
- Services
queryDelay:
unit: Minute # string, one of: Second || Minute
value: 720 # numeric, must be a number less than 1440 minutes (24 hours)
logCollectionEnabled: false # boolean, defaults to 'false'. Set to true if you'd like your source to collect logs. It's a beta functionality available only through direct release channel. Reach out to support@nobl9.com to activate it.
instana:
apiToken: "" # secret
url: https://instance-example.instana.io
FieldTypeDescription
queryDelay.unit
mandatory
enumSpecifies the unit for the query delay. Possible values: Second | Minute.
• Check query delay documentation for default unit of query delay for each source.
queryDelay.value
mandatory
numericSpecifies the value for the query delay.
• Must be a number less than 1440 minutes (24 hours).
• Check query delay documentation for default unit of query delay for each source.
logCollectionEnabled
optional
booleanOptional. Defaults to false. Set to true if you'd like your direct to collect event logs. Beta functionality available only through direct release channel. Reach out to support@nobl9.com to activate it.
releaseChannel
mandatory
enumSpecifies the release channel. Accepted values: beta | stable.
Source-specific fields
instana.apiToken
mandatory
string, secretSee authentication section above for more details.
instana.url
mandatory
stringBase URL that points to your Instana instance. See authentication for more details

Instana agent

Agent configuration in the UI

Follow the instructions below to set up an agent connection. Refer to the section above for the descriptions of the fields.

  1. Select one of the following Release Channels:
    • The stable channel is fully tested by the Nobl9 team. It represents the final product; however, this channel does not contain all the new features of a beta release. Use it to avoid crashes and other limitations.
    • The beta channel is under active development. Here, you can check out new features and improvements without the risk of affecting any viable SLOs. Remember that features in this channel may be subject to change.
  2. Add the URL to connect to your data source (mandatory).

  1. Enter a Project.
  2. Enter a Display Name.
  3. Enter a Name.
  4. Create a Description.
  5. Customize the Query Delay.
  6. Click Add Data Source.

Agent using CLI - YAML

The YAML for setting up an agent connection to Instana looks like this:

apiVersion: n9/v1alpha
kind: Agent
metadata:
name: instana-agent
displayName: Instana Agent
project: default
spec:
description: Agent settings for instana datasource
sourceOf:
- Metrics
- Services
releaseChannel: beta
queryDelay:
unit: Minute
value: 720
instana:
url: https://instance-example.instana.io
FieldTypeDescription
queryDelay.unit
mandatory
enumSpecifies the unit for the query delay. Possible values: Second | Minute.
• Check query delay documentation for default unit of query delay for each source.
queryDelay.value
mandatory
numericSpecifies the value for the query delay.
• Must be a number less than 1440 minutes (24 hours).
• Check query delay documentation for default unit of query delay for each source.
releaseChannel
mandatory
enumSpecifies the release channel. Accepted values: beta | stable.
Source-specific fields
instana.url
mandatory
stringBase URL that points to your Instana instance. See authentication section above for more details
warning

You can deploy only one agent in one YAML file by using the sloctl apply command.

Deploying the Instana agent

When you add the data source, Nobl9 automatically generates a Kubernetes configuration and a Docker command line for you to use to deploy the agent. Both of these are available in the web UI, under the Agent Configuration section. Be sure to swap in your credentials (e.g., replace <INSTANA_API_TOKEN> with your API token).

If you use Kubernetes, you can apply the supplied YAML config file to a Kubernetes cluster to deploy the agent.

# DISCLAIMER: This deployment description contains only the fields necessary for the purpose of this demo.
# It is not a ready-to-apply k8s deployment description, and the client_id and client_secret are only exemplary values.

apiVersion: v1
kind: Secret
metadata:
name: nobl9-agent-dev-instana-myagent
namespace: default
type: Opaque
stringData:
client_id: "Redeemed"
client_secret: "Redeemed"
instana_api_token: "<INSTANA_API_TOKEN>"
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: nobl9-agent-dev-instana-myagent
namespace: default
spec:
replicas: 1
selector:
matchLabels:
nobl9-agent-name: "instana-agent"
nobl9-agent-project: "instana-project"
nobl9-agent-organization: "my-org"
template:
metadata:
labels:
nobl9-agent-name: "instana-agent"
nobl9-agent-project: "instana-project"
nobl9-agent-organization: "my-org"
spec:
containers:
- name: agent-container
image: nobl9/agent:0.69.4
resources:
requests:
memory: "350Mi"
cpu: "0.1"
env:
- name: N9_CLIENT_ID
valueFrom:
secretKeyRef:
key: client_id
name: nobl9-agent-dev-instana-myagent
- name: N9_CLIENT_SECRET
valueFrom:
secretKeyRef:
key: client_secret
name: nobl9-agent-dev-instana-myagent
- name: AUTH_METHOD
value: api_token
- name: API_TOKEN
valueFrom:
secretKeyRef:
key: instana_api_token
name: nobl9-agent-dev-instana-myagent
# The N9_METRICS_PORT is a variable specifying the port to which the /metrics and /health endpoints are exposed.
# The 9090 is the default value and can be changed.
# If you don’t want the metrics to be exposed, comment out or delete the N9_METRICS_PORT variable.
- name: N9_METRICS_PORT
value: "9090"

Creating SLOs with Instana

Instana allows you to create SLOs based on:

  • Infrastructure metrics (for infrastructure components)

  • Application metrics (for defined applications, discovered services, and endpoints)

Infrastructure metrics can be defined as either Threshold metrics or Ratio metrics, but Application metrics can only be defined as Threshold metrics.

See the instructions in the following sections for more details.

Creating SLO in the UI

Follow the instructions below to create an SLO based on a Threshold metric using the Infrastructure type:

  1. Navigate to Service Level Objectives.
  2. Click the plus button button.
  3. In step 1 of the SLO wizard, select the Service the SLO will be associated with.
  4. In step 2, select Instana as the data source for your SLO, then specify the Metric.
  5. Select Threshold metric > Infrastructure.
  6. Enter the Plugin ID (the ID of the plugin available in your monitored system for which you want to retrieve the metric). For more information, refer to the Instana metrics.
  7. Enter the Metric ID, meaning the ID of the metric you want to retrieve. For more information, refer to the Instana metrics.
  8. From the Metric Retrieval Method picklist, select a method to obtain the specific metrics with:
    • Query, using Dynamic Focus search and filter function:
      • To provide the query, go to Infrastructure > Map in the Instana UI and build the query in the input field, for example, entity.selfType:zookeeper AND entity.label:replica.1.
    • Snapshot ID, a unique immutable set of metadata, a snapshot:
      • You can get the Snapshot ID from the URL in Instana’s UI by looking for the snapshotId=[SNAPSHOT_ID] parameter, for example, GbMUvWHy12TTRsIm3Lko4LDAklw.

    For more information, refer to the Instana metrics.

  9. Enter the Query or the Snapshot ID.
  10. In step 3, define a Time Window for the SLO.
  11. In step 4, specify the Error Budget Calculation Method and your Objective(s).
  12. In step 5, add a Name, Description, and other details about your SLO. You can also select Alert policies and Labels on this screen.
  13. When you've finished, click Create SLO.
SLI values for good and total
When choosing the query for the ratio SLI (countMetrics), keep in mind that the values ​​resulting from that query for both good and total:
  • Must be positive.
  • While we recommend using integers, fractions are also acceptable.
    • If using fractions, we recommend them to be larger than 1e-4 = 0.0001.
  • Shouldn't be larger than 1e+20.

Instana metrics

pluginId

Plugins are entities for which metrics are collected. You cannot get the pluginId from the Instana UI. To fetch the list of available plugins, use the following API request:

curl --request GET \
--url https://${BASE_URL}/api/infrastructure-monitoring/catalog/plugins \
--header "authorization: apiToken ${API_TOKEN}"

This request returns a list of plugins. The plugin value is the pluginId while label is used in the Instana UI as a display name:

[
{
"plugin": "zooKeeper",
"label": "ZooKeeper"
}
]

metricId

The metricId is the ID of the metric you want to retrieve. You can get the metricId by using the following API request:

curl --request GET \
--url https://${BASE_URL}/api/infrastructure-monitoring/catalog/metrics/${PLUGIN_ID} \
--header "authorization: apiToken ${API_TOKEN}"
note

PLUGIN_ID is the ID of the plugin you want to retrieve the metricId for. It's the plugin from the /api/infrastructure-monitoring/catalog/plugins response.

This request returns a list of all available metrics for this specific plugin, what you are looking for in the response is metricId. Here's an example:

[
{
"formatter": "UNDEFINED",
"label": "ZooKeepers Max request latency",
"description": "Max request latency",
"metricId": "max_request_latency",
"pluginId": "zooKeeper",
"custom": false
}
]
note

Currently, Nobl9 only allows you to retrieve one metric at a time.


query

The Query is built using Instana's Dynamic Focus search and filter function.

Dynamic Focus queries use Lucene query syntax. The query must be constructed in the Instana UI and copied unchanged. For more information, refer to the Dynamic Focus Query | Instana documentation.

To provide the query, go to Infrastructure > Map in the Instana UI and build the query in the input field, for example, entity.selfType:zookeeper AND entity.label:replica.1.

note

Instana does not allow aggregation of infrastructure metrics. Since Nobl9 can only process a single dataset and there is no aggregation on the N9 side, you have to make sure your query is specific and includes, for example, the name of the target cluster, zone, or node.


snapshotId

A snapshot represents static information about an entity as it was at a specific point in time. For more information, refer to the Search Snapshots | Instana API Docs.

You can get the snapshotId from the URL in Instana's UI by looking for the snapshotId=${SNAPSHOT_ID} parameter. For example,

for this URL: https://${BASE_URL}/#/physical/dashboard?timeline.ws=1728000000&timeline.to=1642719600000&timeline.fm=1642719600000&timeline.ar=false&snapshotId=GbMUvQHy12TTRsIm3Lko4LDAklw

the snapshotId is GbMUvQHy12TTRsIm3Lko4LDAklw.

note

Currently, Nobl9 only allows you to retrieve one snapshotId at a time.

warning

Changing the metadata may result in changing the snapshot. When a new snapshotId is generated for the entity you monitor, you must update your SLO. Otherwise, Nobl9 cannot collect any more measurements.

SLOs using Instana - YAML samples

Generic schema with a description of objects and field validations:

apiVersion: n9/v1alpha
kind: SLO
metadata:
name: string
displayName: string # optional
project: string
spec:
description: string # optional
service: [service name] # name of the service you defined in the same project as the SLO
indicator:
metricSource:
name: [datasource name] # name of the data source you defined
project: [project name] # optional if not defined, project is the same as the SLO
rawMetric:
# exactly one of possible source types which depends on selected metricSource for the SLO
instana: # application XOR infrastructure
metricType: oneOf{"application", "infrastructure"} # mandatory
infrastructure:
metricRetrievalMethod: oneOf{"query", "snapshot"} # mandatory
query: "string" # XOR with snapshotId
snapshotId: "string" # XOR with query
metricId: "string" # mandatory
pluginId: "string" # mandatory
application:
metricId: # mandatory, oneOf{"calls", "erroneousCalls", "errors", "latency"}
aggregation: "" # mandatory, value depends on the metricId type. See notes below
groupBy: # mandatory
tag: "" # mandatory
tagEntity: "" # mandatory, oneOf{"DESTINATION", "SOURCE", "NOT_APPLICABLE"}
tagSecondLevelKey: "" # mandatory
apiQuery: "{}" # mandatory, API query user passes in a JSON format. Must be a valid JSON
includeInternal: false # optional, default value is false
includeSynthetic: false # optional, default value is false

Notes:

  • aggregation - Depends on the value specified for metricId:

    • For calls and erroneousCalls: use sum.

    • For errors: use mean.

    • For latency: use one of the values sum, mean, min, max, p25, p50, p75, p90, p95, p98, p99.


rawMetric

Here’s an example of Instana using rawMetric (Threshold metric) with metricType=”application”, and the Query retrieval method:

apiVersion: n9/v1alpha
kind: SLO
metadata:
name: opentsdb-datanode-latency-95th-application-query
project: instana
spec:
service: instana-service
indicator:
metricSource:
name: instana
project: instana
timeWindows:
- unit: Week
count: 1
calendar:
startTime: 2020-01-21 12:30:00 # date with time in 24h format
timeZone: America/New_York # name as in IANA Time Zone Database
budgetingMethod: Occurrences
objectives:
- displayName: Healthy
value: 10
op: lte
rawMetric:
query:
instana:
metricType: "application"
application:
metricId: "latency"
aggregation: "p95"
groupBy:
tag: "endpoint.name"
tagEntity: "DESTINATION"
tagSecondLevelKey: ""
includeInternal: false
includeSynthetic: false
apiQuery: "{}"
target: 0.99
- displayName: Slower
value: 30
op: lte
rawMetric:
query:
instana:
metricType: "application"
application:
metricId: "latency"
aggregation: "p95"
groupBy:
tag: "endpoint.name"
tagEntity: "DESTINATION"
tagSecondLevelKey: ""
includeInternal: false
includeSynthetic: false
apiQuery: "{}"
target: 0.95
- displayName: Critical
value: 100
op: lte
rawMetric:
query:
instana:
metricType: "application"
application:
metricId: "latency"
aggregation: "p95"
groupBy:
tag: "endpoint.name"
tagEntity: "DESTINATION"
tagSecondLevelKey: ""
includeInternal: false
includeSynthetic: false
apiQuery: "{}"
target: 0.95

countMetric

Here’s an example of Instana using countMetric (Ratio metric) with metricType=”infrastructure”:

apiVersion: n9/v1alpha
kind: SLO
metadata:
name: slo-with-instana-agent-count-metrics-with-infrastructure
displayName: Slo with Instana agent count metrics with infrastructure
spec:
description: Description
service: webapp-service
indicator:
metricSource:
name: instana
timeWindows:
- unit: Week
count: 1
calendar:
startTime: 2020-01-21 12:30:00 # date with time in 24h format
timeZone: America/New_York # name as in IANA Time Zone Database
budgetingMethod: Occurrences
objectives:
- displayName: Good
value: 7.5
target: 0.9
countMetrics:
incremental: false
good:
instana:
metricType: "infrastructure"
infrastructure:
metricRetrievalMethod: "query"
query: "queryGood"
metricId: "metricId"
pluginId: "pluginId"
total:
instana:
metricType: "infrastructure"
infrastructure:
metricRetrievalMethod: "snapshot"
snapshotId: "snapshotId"
metricId: "metricId"
pluginId: "pluginId"

API query example

Here's an example API query for a Threshold > Application metric:

{
"type":"EXPRESSION",
"logicalOperator":"AND",
"elements": [
{
"type":"TAG_FILTER",
"name":"call.inbound_of_application",
"operator":"EQUALS",
"entity":"NOT_APPLICABLE",
"value":"All Services"
},
{
"type":"TAG_FILTER",
"name":"service.name",
"operator":"EQUALS",
"entity":"DESTINATION",
"value":"datanode"
},
{
"type":"TAG_FILTER",
"name":"endpoint.name",
"operator":"EQUALS",
"entity":"DESTINATION",
"value":"GET /"
}
]
}

Querying the Instana server

Nobl9 queries the Instana server on a per-minute basis. This allows Nobl9 to collect up to one data point per minute.

Instana API rate limits

The following rate limits apply to the Instana API:

Agent REST API | Instana documentation

Web REST API | Instana documentation

Infrastructure Metrics | Instana documentation

Application Analyze | Instana documentation

Dynamic Focus Query | Instana documentation

IBM Observability | Instana documentation

Rate Limits | Instana documentation

Agent metrics

Creating SLOs via Terraform

Creating agents via Terraform