Monitoring Instana

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

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