Getting started

Instrumenting a service takes three things: a network and an API key from the dashboard, an SDK in your process, and a few capture calls where you already handle protocol traffic. This page covers everything the two protocols share. When you’re ready to write code, go to the guide for the protocol your service speaks.

OCPP server

Capture WebSocket frames from your charge points.

OCPI server

Capture roaming exchanges with your partners.

Supported languages

SDK	Package	Requires	Status
Go	`github.com/evpanda-labs/evpanda-go`	Go 1.24+	Published, stable
Node	`@evpanda/sdk`	Node 18+	`0.1.0` pending publish
Python	`evpanda`	Python 3.12+	Preview, install from source

go get github.com/evpanda-labs/evpanda-go

npm add @evpanda/sdk

pip install "evpanda[zstd]"

Availability, honestly. The Go SDK is published and is the reference implementation the others track.The npm registry currently serves an older @evpanda/sdk; the API documented here is 0.1.0. Until it ships, the OCPP session handle and the OCPI adapters are not available — the flat capture calls are.The Python SDK is not on PyPI yet. Install it from source, and note it has no HTTP adapters:

pip install "git+https://github.com/evpanda-labs/evpanda-py"

Source and API reference

evpanda-go · pkg.go.dev · evpanda-node · evpanda-py

Optional compression dependency

Compression defaults to zstd, which needs one optional package in Node and Python. Without it the SDK falls back to gzip silently.

SDK	To get zstd
Go	Included
Node	`npm add @mongodb-js/zstd`
Python	`pip install "evpanda[zstd]"`

What the SDK does

The SDK is passive. It observes traffic your application already handles — it never sits in the request path, never blocks on the network, and never fails your process if EVPanda is unreachable.

Capture never blocks your application

A capture call validates the identity, enforces a size cap, redacts secrets, copies the payload, writes it to an in-process buffer, and returns. No I/O, no locks your code contends on. Delivery happens on a background worker.

Memory is capped, and the SDK drops its own data first

The buffer has a ceiling you set. When delivery stalls the SDK evicts its oldest captures rather than growing without limit or applying backpressure to your service.

Secrets never leave your process

OCPI headers pass through an allowlist before anything is buffered, so Authorization, Cookie, and API keys are dropped at capture. Tokens in OCPI /credentials bodies are masked. See What gets captured.

A bad config can't crash your boot

If the endpoint or API key is wrong the client starts inert: every capture is a no-op and the error is reported to you. Your service still boots.

Get an API key

A network is the container for everything EVPanda records about one of your systems, and an API key is scoped to exactly one network.

Create a network

In app.evpanda.io, create a Charger network for an OCPP CSMS or a Roaming network for an OCPI server. One per system, per environment.

Generate a key

Open the network’s Settings tab and generate a key. The raw value — evp_sk_… — is shown once. EVPanda stores only a hash of it.

Put it in the environment

export EVPANDA_API_KEY="evp_sk_..."

Every SDK falls back to EVPANDA_API_KEY when no key is passed in code, which keeps the key out of your source.

See Networks for network settings, key rotation, and what a key can and cannot do.

Start a client

The protocol is the client. OCPI and OCPP have separate client types, separate configs, and separate API keys. Start one at boot and share it across your process — each client runs its own background worker and its own buffer.

import evpanda "github.com/evpanda-labs/evpanda-go"

// APIKey omitted → read from EVPANDA_API_KEY.
panda, err := evpanda.StartOCPP(evpanda.OCPPConfig{
    BaseConfig: evpanda.BaseConfig{Endpoint: "https://ingest.evpanda.io"},
})
if err != nil {
    log.Printf("evpanda: %v (running inert)", err)
}
defer func() { _ = panda.Close() }()

import { OCPPClient } from "@evpanda/sdk";

// apiKey omitted → read from EVPANDA_API_KEY.
export const panda = OCPPClient.start({
  endpoint: "https://ingest.evpanda.io",
  debug: process.env.NODE_ENV !== "production",
});

from evpanda import OCPPClient, OCPPConfig

# api_key omitted → read from EVPANDA_API_KEY.
panda = OCPPClient.start(
    OCPPConfig(endpoint="https://ingest.evpanda.io", debug=True)
)

Swap OCPP for OCPI if that’s what your service speaks. Both clients are safe for concurrent use.

Log the startup error. An inert client behaves exactly like a healthy one on an idle system — silent, no panics, no failures — so a swallowed config error looks identical to “no traffic yet”.In Go the error comes back from Start*. In Node and Python nothing is reported unless debug is on, which is why both examples above turn it on.

Configuration

endpoint and apiKey are hard-required. Every other option is a tunable: an out-of-range value falls back to its default and says so in the logs, rather than failing.

Purpose	Go	Node	Python	Default
Ingestion base URL	`Endpoint`	`endpoint`	`endpoint`	required
API key	`APIKey`	`apiKey`	`api_key`	`$EVPANDA_API_KEY`
Buffer ceiling	`MaxBufferBytes`	`bufferCapacity`	`buffer_capacity`	32 MiB / 10,000 msgs
Per-capture cap	`MaxCaptureBytes`	`maxCaptureBytes`	`max_capture_bytes`	65536 bytes
Flush cadence	`FlushInterval`	`flushInterval`	`flush_interval`	5s / 5000ms / 5.0s
Drain deadline	`DrainTimeout`	`drainTimeout`	`drain_timeout`	10s, minimum 5s
Compression	`Compression`	`compression`	`compression`	`zstd`
Log verbosity	`LogMode`	`debug`	`debug`	see below
Log destination	`Logger`	`logger`	`logger`	`slog.Default()` / `console`
Extra OCPI headers	`OCPIAllowedHeaders`	`ocpiAllowedHeaders`	`ocpi_allowed_headers`	none

Go
Node
Python

Intervals are time.Duration. The buffer is capped by bytes, so the number you set is the memory footprint, not an estimate of it.

evpanda.StartOCPI(evpanda.OCPIConfig{
    BaseConfig: evpanda.BaseConfig{
        Endpoint:       "https://ingest.evpanda.io",
        MaxBufferBytes: 64 << 20, // 64 MiB
        FlushInterval:  2 * time.Second,
        LogMode:        evpanda.LogModeDebug,
    },
    OCPIAllowedHeaders: []string{"x-trace-id"},
})

LogMode is LogModeSilent, LogModeErrors (default), or LogModeDebug. The EVPANDA_LOG environment variable sets it without a code change; an explicit config value wins.

Intervals are milliseconds. The buffer is capped by message count, so worst-case memory is roughly bufferCapacity × maxCaptureBytes.

OCPIClient.start({
  endpoint: "https://ingest.evpanda.io",
  bufferCapacity: 50_000,
  flushInterval: 2_000,
  debug: true,
  logger: pino({ name: "evpanda" }),
  ocpiAllowedHeaders: ["x-trace-id"],
});

debug is a master switch — with it off, the SDK is completely silent, including about config errors. The logger interface is four methods (debug, info, warn, error), so pino, winston, bunyan, and console all satisfy it.

Intervals are float seconds, matching time.sleep and socket timeouts. The buffer is capped by message count.

OCPIClient.start(
    OCPIConfig(
        endpoint="https://ingest.evpanda.io",
        buffer_capacity=50_000,
        flush_interval=2.0,
        debug=True,
        logger=logging.getLogger("evpanda"),
        ocpi_allowed_headers=["x-trace-id"],
    )
)

debug is a master switch — with it off, the SDK is completely silent. With logger=None it uses logging.getLogger("evpanda").

Sizing the buffer

The buffer absorbs a delivery stall. Size it for how long you want to survive one: message rate × average size × seconds. At 400 messages/second and 500 bytes each — roughly a 10,000-charger CSMS — one minute of stalled delivery is about 12 MB. The 32 MiB Go default covers about two and a half minutes of that: enough for a blip, small enough for an ordinary container limit.

Don’t set the buffer ceiling below the per-capture cap. A full-size capture could then never fit, so every large message would be dropped after being redacted.

How delivery works

One background worker per client owns delivery. It flushes when 1,000 messages are waiting or the flush interval elapses, whichever comes first, compresses the batch, and POSTs it to https://ingest.evpanda.io.

Response	Treated as
`200`	Delivered
`400`, `401`, `413`	Permanent — dropped immediately, never retried
`5xx`, network error, timeout	Retried with jittered exponential backoff, five attempts

Retries are deliberately not configurable: an SDK on a customer’s hot path that retries aggressively against a struggling API turns a partial outage into a full one.

Where data can be lost

Five places, all counted:

Counter	Cause
`DroppedInvalid`	Identity failed validation
`DroppedOversize`	Body or frame over the per-capture cap
`DroppedEvicted`	Buffer full, oldest evicted
`DroppedUndeliverable`	Retries exhausted, or a permanent rejection
`DroppedPanic`	A recovered panic inside the SDK — a bug, please report it

Shut down cleanly

Stop accepting traffic first, then drain. Draining while chargers or partners are still sending is a race you’ll lose.

srv.Shutdown(ctx)                  // stop accepting…
if err := panda.Shutdown(ctx); err != nil {
    log.Printf("evpanda: %v", err) // …then drain
}

server.close();
await panda.close();

server.shutdown()
panda.close()

Close is idempotent, and captures made after it are safe no-ops.

Node: close() returns a promise. Not awaiting it is the difference between draining the buffer and discarding it.Go: Shutdown(ctx) uses your context’s deadline; Close() uses the configured DrainTimeout. Both return ErrDrainIncomplete if the deadline passed with messages still buffered.Python: close() blocks while it drains, up to drain_timeout. Call it from your shutdown path, not from a request handler.

flush() forces an immediate delivery and waits for it — useful in tests and at shutdown, never on a request path.

Check that it’s working

Confirm the client is live, not inert

In Go, the error from Start* is nil. In Node and Python, debug is on and no config error appeared at startup.

Drive real traffic

Connect a charge point, or make one OCPI call in each direction. Synthetic traffic that skips your auth layer won’t exercise identity resolution — the part that usually breaks.

Wait one flush interval

Five seconds by default, or call flush().

Check the dashboard

Messages appear under your network. Chargers and platforms are created automatically the first time they send traffic, so a new entity appearing is itself confirmation.

Check both directions

The step people skip. Confirm you see frames you sent as well as frames you received. Half-instrumented is the most common production state, and it silently disables the most valuable checks.

Counters and logs

Go exposes the delivery counters directly, on any client — including an inert or closed one:

s := panda.Stats()
log.Printf("evpanda: captured=%d invalid=%d oversize=%d evicted=%d undeliverable=%d buffered=%d",
    s.Captured, s.DroppedInvalid, s.DroppedOversize,
    s.DroppedEvicted, s.DroppedUndeliverable, s.BufferedMessages)

They are always on, so you can feed them straight into your metrics:

prometheus.MustRegister(prometheus.NewCounterFunc(
    prometheus.CounterOpts{Name: "evpanda_dropped_total"},
    func() float64 { return float64(panda.Stats().TotalDropped()) },
))

Go also logs by default, at a bounded rate — at most one summary line per minute, and nothing at all while healthy:

level=WARN msg="evpanda: captures dropped" window=1m0s captured=12 invalid_identity=148302 buffered=0 buffer_bytes=0

Node and Python don’t expose a counters API yet. Turn on debug to get the same picture in your logs, and use the dashboard’s message volume to confirm an integration is healthy.

What to alert on

Alert	Condition
Capture stalled	`Captured` flat while your service is serving traffic
Identity failures	`DroppedInvalid` rising — identity resolution regressed
Delivery failing	`DroppedUndeliverable` rising — network, egress, or a revoked key
Buffer pressure	Buffer sustained above half the ceiling; eviction is next

Alert on rates, not totals: the counters are monotonic since client start, so a total tells you something once went wrong while a rate tells you it is going wrong now.

Troubleshooting

Nothing arrives, and Captured is 0

Either the client is inert or the capture calls aren’t running.Check the startup error (Go) or turn on debug (Node, Python). Confirm EVPANDA_API_KEY is set in the environment your service actually runs in — set in your shell, absent from the container is the classic miss — and that endpoint is https://ingest.evpanda.io with no path.

Nothing arrives, and DroppedInvalid is climbing

Identity resolution is failing. This is the most common integration fault by a wide margin.For OCPI, the usual cause is a capture adapter mounted before the middleware that authenticates the partner, so nothing has an identity yet. Move capture after auth. See Identity.

Nothing arrives, and DroppedUndeliverable is climbing

Capture works, delivery doesn’t. Check egress first:

curl -sS https://ingest.evpanda.io/health
# {"status":"ok"}

If that fails, allowlist ingest.evpanda.io on port 443. If it succeeds, suspect the key: a revoked or wrong-protocol key returns 401, which is permanent and never retried. An OCPP client needs a charger network’s key; an OCPI client needs a roaming network’s key.

Messages deliver but don't show up

The ingestion API validates each message independently and reports {"captured": N, "failed": M}. Messages counted in failed were rejected after a successful delivery.Usual causes, in order:

An OCPP message with no tenant pair. The API currently requires tenant_id and tenant_name on OCPP messages even though the SDKs treat them as optional.
An OCPI exchange with no status code. It must be between 100 and 599; there is no null form.
An identity field over its limit. Tenant name is 32 characters; the rest are 64.

See Identity.

Only half the traffic appears

You are capturing one direction. For OCPP, that means the write path isn’t instrumented; for OCPI, that the outbound HTTP client isn’t wrapped.It matters more than it looks: without both directions the validation engine can’t pair requests with responses, so you lose every timeout, orphan, and duplicate-ID finding.

Bodies are missing or truncated

A body or frame over maxCaptureBytes (64 KiB by default) drops the whole message rather than storing a truncated one. Raise the cap — 256 KiB is reasonable for a roaming server — and raise the buffer ceiling with it.

Memory grew after adding the SDK

Expected and bounded: the buffer holds undelivered captures up to its ceiling. If that’s more than your pod can afford, lower the ceiling. A healthy client idles far below it.

Still stuck? Mail support@evpanda.io with the SDK and version, the network name and protocol, and a counter snapshot or debug log covering a minute of live traffic.

No SDK for your language?

The ingestion API is a small HTTP contract: two routes, one auth header, one response shape.

curl -sS https://ingest.evpanda.io/v1/ocpp \
  -H "X-API-Key: $EVPANDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[ ... ]}'
# {"captured":1,"failed":0}

POST /v1/ocpp and POST /v1/ocpi each take up to 1,000 messages per batch, optionally gzip- or zstd-compressed, capped at 5 MB compressed and 20 MB decompressed. Mail support@evpanda.io for the full message schemas. If you implement your own client, copy the behaviors that make an SDK safe on a hot path: never block the caller, bound your memory, batch, retry only 5xx and network errors, redact before you buffer, and count what you drop.

OCPP server

The full integration, step by step, in Go, Node, and Python.

OCPI server

The same, plus the drop-in HTTP adapters.

Core concepts

SDK integration

Getting started

OCPP server

OCPI server

Supported languages

Source and API reference

Optional compression dependency

What the SDK does

Get an API key

Start a client

Configuration

Sizing the buffer

How delivery works

Where data can be lost

Shut down cleanly

Check that it’s working

Counters and logs

What to alert on

Troubleshooting

No SDK for your language?

Next

OCPP server

OCPI server

OCPP server

OCPI server

​Supported languages

Source and API reference

​Optional compression dependency

​What the SDK does

​Get an API key

​Start a client

​Configuration

​Sizing the buffer

​How delivery works

​Where data can be lost

​Shut down cleanly

​Check that it’s working

​Counters and logs

​What to alert on

​Troubleshooting

​No SDK for your language?

​Next

OCPP server

OCPI server

Supported languages

Optional compression dependency

What the SDK does

Get an API key

Start a client

Configuration

Sizing the buffer

How delivery works

Where data can be lost

Shut down cleanly

Check that it’s working

Counters and logs

What to alert on

Troubleshooting

No SDK for your language?

Next