WSO2 API Manager

WSO2 API Manager is an open-source full-lifecycle API management platform; its gateway is the front door for every API it publishes. The gateway’s failure modes are the familiar ones — it can serve faults, serve slowly, or stop serving entirely — plus two that come from running on a JVM: the server narrates trouble into wso2carbon.log, and the heap fills up before things fall over. This system type has a starter check for each.

Key: wso2-apim · applied automatically to services emitting wso2- or org_wso2-prefixed metrics.

Getting the telemetry

Full coverage takes three signals from three places — traces from API-M itself, logs from wso2carbon.log, and JVM metrics from an agent.

Traces. API-M 4.x speaks OpenTelemetry natively: enable the OTLP remote tracer in deployment.toml and point it at a Collector that attaches your Sluicio ingest key (point the Collector at Sluicio):

deployment.toml

[apim.open_telemetry]
remote_tracer.enable = true
remote_tracer.name = "otlp"
remote_tracer.url = "http://otel-collector:4317"

WSO2’s docs also show [[apim.open_telemetry.remote_tracer.properties]] entries for attaching auth headers — you don’t need them when the Collector in between adds the ingest key. The full option set is in WSO2’s OpenTelemetry documentation; restart the server after editing.

Logs. API-M writes its story to <APIM_HOME>/repository/logs/wso2carbon.log. Tail it with the Collector’s filelog receiver, parsing the severity so error-level records are recognisable:

otel-collector-config.yaml (receivers)

receivers:
  filelog/wso2:
    include:
      - /opt/wso2am/repository/logs/wso2carbon.log
    operators:
      - type: regex_parser
        regex: '\]\s+(?P<sev>TRACE|DEBUG|INFO|WARN|ERROR|FATAL)\s+\{'
        severity:
          parse_from: attributes.sev

The regex matches the default TID: [...] [...] [timestamp] LEVEL {class} - message layout — if you’ve customised the log4j2 pattern, adjust it to match. The severity parsing is what makes the error-log check work; without it every record arrives unleveled.

JVM metrics (optional, but the heap check needs them). Either attach the OpenTelemetry Java agent to the gateway JVM — it emits the stable-semconv jvm.memory.used the heap check expects — or run the Prometheus jmx_exporter agent and scrape it with the prometheus receiver.

What Sluicio detects

Metrics whose names start with wso2 or org_wso2 — the shape jmx_exporter produces from API-M’s org.wso2.carbon MBeans.

Tracing-only deployments aren’t auto-detected

The JVM metric names (jvm.*) are too generic for detection — every Java service emits them — so an API-M that sends only traces (or traces plus Java-agent metrics) won’t take on the type by itself. Set the type on the service manually; the starter checks work the same either way.

Starter checks

Check	Condition	Severity	Why it matters
Failed API invocations	Any error trace in a 5-minute window	Warning	Callers are getting faults from the gateway or a backend behind it. See the note below — this check may need a cell setting.
High p95 response time	p95 request latency ≥ 2,000 ms over 5 minutes	Warning	The gateway is slow — mediation overhead, a slow backend or a struggling JVM; either way, API consumers feel it.
Gateway silent	No traces received for 15 minutes	Warning	A gateway that stops reporting is down, cut off from the Collector, or has lost its tracing config.
Error logs spiking	≥ 10 error-level log records in the window	Warning	wso2carbon.log is narrating a problem — deployment failures, backend connection errors, throttling issues — before users report it.
JVM heap high	jvm.memory.used (heap) > 1.5 GiB	Warning	Heap pressure precedes full-GC churn and eventually an OutOfMemoryError. Also shown as a display tile on the service, so you see the trend, not just the breach.

The failed-invocations check may need “Treat HTTP 5xx as errors”

If your API-M version records a gateway fault only as a 5xx status-code attribute on the span and leaves the span status unset, an unconfigured cell counts those traces as healthy. Enable Settings → System → General → “Treat HTTP 5xx as errors” (admin-only, off by default) so 5xx spans are stored as errors — the KrakenD guide explains the mechanics, which apply to any gateway with this span shape.

Best-effort starting points — verify what your version emits

WSO2’s telemetry surface varies with API-M version, the tracer implementation and your log4j2 configuration. These checks are honest starting points, not guarantees: after applying the type, confirm each one against what actually arrives — traces in the trace view, log severities in the log view, metric names in the service’s metric catalog — and tune the rules on the service.

Tuning notes

• p95 threshold. 2,000 ms is a conservative default for a mediating gateway. If your APIs are pass-through and fast, run far tighter — set it from your real latency profile with headroom above normal p95.
• Silence window. 15 minutes suits steady traffic. A gateway that’s quiet at night will false-positive — widen the window, or scope the check to business hours.
• Error-log spike assumes wso2carbon.log flows to Sluicio (the filelog receiver above). API-M can be chatty at error level during redeployments — if routine operations trip the check, raise the floor above your normal error chatter.
• Heap threshold. 1.5 GiB assumes the default 2 GiB -Xmx (~75% of heap). Set it to 70–80% of your configured -Xmx. And if your JVM metrics come from jmx_exporter rather than the Java agent, the metric is named differently (jvm_memory_bytes_used and friends) — point the rule at the name your setup actually emits.

Sharing

Like every system type, this one is a portable YAML file — export it from the UI, import it on another cell, commit it to git. The community copy lives in github.com/SLUICIO/sluicio-system-types as types/wso2-apim.systemtype.yaml, and to adapt it for your organisation, create your own type reusing the wso2-apim key — your version overrides the built-in.