monitoring-instana

name	monitoring-instana
description	Use when working with Instana — instana application performance monitoring with infrastructure discovery, service endpoint analysis, incident management, smart alert configuration, and dependency mapping. Covers automatic topology, call analysis, trace grouping, SLI/SLO tracking, and infrastructure health. Use when analyzing service performance, investigating incidents, reviewing infrastructure topology, or managing alerts via Instana API.
connection_type	instana
preload	false

Instana Monitoring Skill

Monitor and analyze infrastructure and applications using the Instana API.

API Conventions

Authentication

Instana API uses apiToken header — injected by connection. Never hardcode tokens.

Base URL

• API: https://<tenant>-<unit>.instana.io/api/
• Use connection-injected INSTANA_BASE_URL.

Output Rules

• TOKEN EFFICIENCY: Target <=50 lines per output
• Use jq to extract entity snapshots and metric values
• NEVER dump full infrastructure snapshots — summarize by type

Core Helper Function

#!/bin/bash

instana_api() {
    local method="$1"
    local endpoint="$2"
    local data="${3:-}"

    if [ -n "$data" ]; then
        curl -s -X "$method" \
            -H "authorization: apiToken ${INSTANA_API_TOKEN}" \
            -H "Content-Type: application/json" \
            "${INSTANA_BASE_URL}/api${endpoint}" \
            -d "$data"
    else
        curl -s -X "$method" \
            -H "authorization: apiToken ${INSTANA_API_TOKEN}" \
            "${INSTANA_BASE_URL}/api${endpoint}"
    fi
}

instana_metrics() {
    local entity_type="$1"
    local metric="$2"
    local duration="${3:-3600000}"  # milliseconds
    local to=$(( $(date +%s) * 1000 ))
    local from=$(( to - duration ))

    instana_api POST "/infrastructure-monitoring/metrics" \
        "{\"plugin\":\"${entity_type}\",\"metrics\":[\"${metric}\"],\"timeFrame\":{\"windowSize\":${duration},\"to\":${to}}}"
}

Parallel Execution

{
    instana_api GET "/application-monitoring/applications" &
    instana_api GET "/events?windowSize=3600000" &
    instana_api GET "/infrastructure-monitoring/snapshots?size=20" &
}
wait

Anti-Hallucination Rules

NEVER assume application IDs, service names, or entity types. ALWAYS discover first.

Phase 1: Discovery

#!/bin/bash
echo "=== Applications ==="
instana_api GET "/application-monitoring/applications" \
    | jq -r '.items[] | "\(.id)\t\(.label)"' | head -20

echo ""
echo "=== Services ==="
instana_api GET "/application-monitoring/services" \
    | jq -r '.items[] | "\(.id)\t\(.label)\t\(.technologies | join(","))"' | head -20

echo ""
echo "=== Infrastructure Snapshot Types ==="
instana_api GET "/infrastructure-monitoring/snapshots?size=50" \
    | jq -r '[.items[].plugin] | group_by(.) | map("\(.[0]): \(length)") | .[]' | head -15

echo ""
echo "=== Recent Events ==="
instana_api GET "/events?windowSize=3600000" \
    | jq -r '.[] | "\(.type)\t\(.text[0:60])"' | head -10

Common Operations

Infrastructure Discovery & Health

#!/bin/bash
echo "=== Infrastructure Overview ==="
{
    echo "--- Host Snapshots ---"
    instana_api GET "/infrastructure-monitoring/snapshots?plugin=host&size=20" \
        | jq -r '.items[] | "\(.snapshotId)\t\(.label)\tcpu:\(.data.cpu.user // "N/A")%"' | head -15 &

    echo "--- Container Snapshots ---"
    instana_api GET "/infrastructure-monitoring/snapshots?plugin=dockerContainer&size=20" \
        | jq -r '.items[] | "\(.label)\t\(.data.state // "unknown")"' | head -10 &

    echo "--- Process Snapshots ---"
    instana_api GET "/infrastructure-monitoring/snapshots?plugin=process&size=10" \
        | jq -r '.items[] | "\(.label)"' | head -10 &
}
wait

Service Endpoint Analysis

#!/bin/bash
APP_ID="${1:?Application ID required}"

echo "=== Service Endpoints ==="
instana_api GET "/application-monitoring/applications/${APP_ID}/services" \
    | jq -r '.items[] | "\(.id)\t\(.label)\t\(.technologies | join(","))"' | head -15

echo ""
echo "=== Endpoint Performance ==="
TO=$(( $(date +%s) * 1000 ))
FROM=$(( TO - 3600000 ))

instana_api POST "/application-monitoring/analyze/call-groups" \
    "{\"timeFrame\":{\"to\":${TO},\"windowSize\":3600000},\"tagFilterExpression\":{\"type\":\"TAG_FILTER\",\"name\":\"application.id\",\"operator\":\"EQUALS\",\"value\":\"${APP_ID}\"},\"groupBy\":[\"endpoint.name\"],\"metrics\":[{\"metric\":\"latency\",\"aggregation\":\"MEAN\"},{\"metric\":\"calls\",\"aggregation\":\"SUM\"},{\"metric\":\"errors\",\"aggregation\":\"SUM\"}]}" \
    | jq -r '.items[:15][] | "\(.name)\tlatency:\(.metrics.latency.MEAN // 0)ms\tcalls:\(.metrics.calls.SUM // 0)\terrors:\(.metrics.errors.SUM // 0)"'

Incident Management

#!/bin/bash
echo "=== Open Incidents ==="
instana_api GET "/events?windowSize=86400000" \
    | jq -r '.[] | select(.state == "OPEN") | "\(.id)\t\(.type)\t\(.severity)\t\(.text[0:60])"' | head -15

echo ""
echo "=== Incident Types ==="
instana_api GET "/events?windowSize=86400000" \
    | jq -r '[.[] | .type] | group_by(.) | map("\(.[0]): \(length)") | .[]'

echo ""
echo "=== Critical Events ==="
instana_api GET "/events?windowSize=86400000" \
    | jq -r '.[] | select(.severity >= 10) | "\(.start / 1000 | strftime("%Y-%m-%d %H:%M"))\t\(.text[0:80])"' | head -10

Smart Alert Configuration

#!/bin/bash
echo "=== Alert Configurations ==="
instana_api GET "/events/settings/alerts" \
    | jq -r '.[] | "\(.id)\t\(.name)\t\(.enabled)\t\(.severity)"' | head -20

echo ""
echo "=== Alert Channels ==="
instana_api GET "/events/settings/alertingChannels" \
    | jq -r '.[] | "\(.id)\t\(.name)\t\(.kind)"' | head -15

echo ""
echo "=== Website Alert Rules ==="
instana_api GET "/events/settings/website-alert-configs" \
    | jq -r '.[] | "\(.id)\t\(.name)\t\(.enabled)"' | head -10

Trace Analysis

#!/bin/bash
echo "=== Recent Slow Traces ==="
TO=$(( $(date +%s) * 1000 ))

instana_api POST "/application-monitoring/analyze/traces" \
    "{\"timeFrame\":{\"to\":${TO},\"windowSize\":3600000},\"order\":{\"by\":\"duration\",\"direction\":\"DESC\"},\"pagination\":{\"page\":1,\"pageSize\":15}}" \
    | jq -r '.items[] | "\(.traceId)\t\(.duration)ms\t\(.rootSpan.name[0:40])\terrors:\(.errorCount)"' | head -15

echo ""
echo "=== Error Traces ==="
instana_api POST "/application-monitoring/analyze/traces" \
    "{\"timeFrame\":{\"to\":${TO},\"windowSize\":3600000},\"tagFilterExpression\":{\"type\":\"TAG_FILTER\",\"name\":\"call.erroneous\",\"operator\":\"EQUALS\",\"value\":\"true\"},\"pagination\":{\"page\":1,\"pageSize\":10}}" \
    | jq -r '.items[] | "\(.traceId)\t\(.duration)ms\t\(.rootSpan.name[0:40])"'

Output Format

Present results as a structured report:

Monitoring Instana Report
═════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Counter-Rationalizations

Shortcut	Counter	Why
"I'll skip discovery and check known resources"	Always run Phase 1 discovery first	Resource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"	Follow the full discovery → analysis flow	Quick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"	Audit configuration explicitly	Defaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"	Always check relevant metrics when available	API/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"	Try the command and report the actual error	Assumed permission failures prevent useful investigation; actual errors are informative

Common Pitfalls

• Time format: Instana uses milliseconds since epoch — multiply Unix seconds by 1000
• Window size: windowSize is in milliseconds — 3600000=1h, 86400000=24h
• Tag filter expressions: Complex nested JSON structure — use TAG_FILTER type with EQUALS/CONTAINS
• Auto-discovery: Instana auto-discovers infrastructure — entity snapshots change dynamically
• Plugin types: host, dockerContainer, process, jvmRuntimePlatform, kubernetes etc.
• Pagination: Use page and pageSize in request body — not query parameters
• Severity levels: Numeric 1-10 — higher is more critical, 10=critical
• API token scope: Tokens have scoped permissions — some endpoints may return 403