Skip to main content

Instana

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 in the Nobl9 UI

To add Instana as a data source in Nobl9 using the Agent or Direct connection method, follow these steps:

  1. Navigate to Integrations > Sources.

  2. Click the plus button button.

  3. Click the Instana icon.

  4. Choose Direct or Agent, 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. 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.

  2. 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.

  3. Select a Project (mandatory).
    Specifying a project is helpful when multiple users are spread across multiple teams or projects. When the Project field is left blank, a default value appears.

  4. Enter a Display name (optional).
    You can enter a friendly name with spaces in this field.

  5. Enter a Name (mandatory).
    The name is mandatory and can only contain lowercase, alphanumeric characters and dashes (for example, my-project-name). This field is populated automatically when you enter a display name, but you can edit the result.

  6. Enter a Description (optional).
    Here you can add details such as who is responsible for the integration (team/owner) and the purpose of creating it.

  7. Click the Add Data Source button.

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. Add the URL to connect to your data source (mandatory).

  2. Select a Project (mandatory).

  3. Enter a Display name (optional).

  4. Enter a Name (mandatory).

  5. Enter a Description (optional).

  6. Click the Add Data Source button.

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:latest
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

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).
  7. For more information, refer to the Instana Metrics | Nobl9 Documentation.

  8. Enter the Metric ID, meaning the ID of the metric you want to retrieve.
  9. For more information, refer to the Instana Metrics | Nobl9 Documentation.

  10. From the Metric Retrieval Method picklist, select a method to obtain the specific metrics with:
  11. 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.

    Build the query using entity name filters - be as specific as possible. Since Nobl9 can only process a single dataset and there is no aggregation on the N9 side, the applied filter must point to the exact entity you want to be observed.

    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 | Nobl9 Documentation.

  12. Enter the Query or the Snapshot ID.
  13. In step 3, define a Time Window for the SLO.
  14. In step 4, specify the Error Budget Calculation Method and your Objective(s) .
  15. In step 5, add a Name, Description, and other details about your SLO. You can also select Alert Policies and Labels on this screen.
  16. When you’ve finished, click Create SLO.

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 YAML examples

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 YAML examples

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 1 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