Getting started

Everything on this page is the same for both protocols. When you are ready to write capture 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.

Install

SDK	Package	Requires
Go	`github.com/evpanda-labs/evpanda-go`	Go 1.24+
Node	`@evpanda/sdk`	Node 22.15+
Python	`evpanda`	Python 3.12+

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

npm install @evpanda/sdk

pip install evpanda

Every SDK compresses batches with zstd. Go bundles it through one dependency, Node uses node:zlib (which is why it needs Node 22.15, where zstd landed), and Python brings zstandard. Optional extras, needed only for the adapter you use:

# none: the OCPI adapters are stdlib only

# express, axios and ws are optional peers
npm install express axios ws

pip install 'evpanda[httpx]'     # httpx transports
pip install 'evpanda[requests]'  # requests adapter

Get an API key

Create a network

In the dashboard, create a Charger network for an OCPP CSMS or a Roaming network for an OCPI server.

Generate a key

Under the network’s Settings tab. The raw value is shown once.

Export it

export EVPANDA_API_KEY="evp_sk_..."

See Networks for settings, scoping, and rotation.

Start a client

The protocol is the client. Start one at boot and share it across your process; each client runs one background worker and one buffer. The API key is the only thing you must supply. endpoint defaults to the production ingestion API, so leave it unset unless you are pointing at another environment.

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

// APIKey comes from EVPANDA_API_KEY; Endpoint defaults to production.
panda, err := evpanda.StartOCPP(evpanda.OCPPConfig{})
if err != nil {
    log.Printf("evpanda: %v (running inert)", err)
}
defer func() { _ = panda.Close() }()

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

// apiKey comes from EVPANDA_API_KEY; endpoint defaults to production.
export const panda = startOCPP();
if (panda.error) log.warn(`${panda.error.message} (running inert)`);

import evpanda

# api_key comes from EVPANDA_API_KEY; endpoint defaults to production.
panda = evpanda.start_ocpp()
if panda.error:
    log.warning("%s (running inert)", panda.error)

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

A bad config never crashes your boot

start always returns a usable client. If the config is bad you get an inert one that captures nothing, and the reason comes back as an error (Go) or on .error (Node, Python). Only two things can fail: a missing API key and a malformed endpoint. Both are matchable, which is useful because a missing key is usually a deployment problem while a bad endpoint is a code one.

panda, err := evpanda.StartOCPI(cfg)
if errors.Is(err, evpanda.ErrAPIKey) {
    log.Fatal("EVPANDA_API_KEY is not set in this environment")
}
if err != nil {
    log.Printf("evpanda: %v (running inert)", err)
}

import { ApiKeyError, startOCPI } from "@evpanda/sdk";

const panda = startOCPI(config);
if (panda.error instanceof ApiKeyError) {
  throw new Error("EVPANDA_API_KEY is not set in this environment");
}
if (panda.error) log.warn(`${panda.error.message} (running inert)`);

panda = evpanda.start_ocpi(config)
if isinstance(panda.error, evpanda.APIKeyError):
    raise SystemExit("EVPANDA_API_KEY is not set in this environment")
if panda.error:
    log.warning("%s (running inert)", panda.error)

Log the startup fault. An inert client behaves exactly like a healthy one on an idle system, so a swallowed config error looks identical to “no traffic yet”.

Configuration

Every field except the API key takes its default when left at its zero value. An out of range value falls back to that default with a warning rather than failing.

Go	Node	Python	Default
`Endpoint`	`endpoint`	`endpoint`	`https://ingest.evpanda.io`
`APIKey`	`apiKey`	`api_key`	`$EVPANDA_API_KEY`, required
`MaxBufferBytes`	`maxBufferBytes`	`max_buffer_bytes`	32 MiB, minimum 64 KiB
`MaxCaptureBytes`	`maxCaptureBytes`	`max_capture_bytes`	64 KiB
`FlushInterval`	`flushInterval`	`flush_interval`	5s / 5000ms / 5.0s
`DrainTimeout`	`drainTimeout`	`drain_timeout`	10s, minimum 5s
`LogMode`	`logMode`	`log_mode`	`errors`
`Logger`	`logger`	`logger`	`slog.Default()` / `console` / `getLogger("evpanda")`
`OCPIAllowedHeaders`	`ocpiAllowedHeaders`	`ocpi_allowed_headers`	none, OCPI only

Go takes time.Duration, Node takes milliseconds, Python takes float seconds.

panda, err := evpanda.StartOCPI(evpanda.OCPIConfig{
    BaseConfig: evpanda.BaseConfig{
        MaxBufferBytes: 64 << 20,
        FlushInterval:  2 * time.Second,
        LogMode:        evpanda.LogModeDebug,
    },
    OCPIAllowedHeaders: []string{"x-trace-id"},
})

const panda = startOCPI({
  maxBufferBytes: 64 * 1024 * 1024,
  flushInterval: 2_000,
  logMode: "debug",
  ocpiAllowedHeaders: ["x-trace-id"],
});

panda = evpanda.start_ocpi(
    evpanda.OCPIConfig(
        max_buffer_bytes=64 << 20,
        flush_interval=2.0,
        log_mode="debug",
        ocpi_allowed_headers=["x-trace-id"],
    )
)

Sizing the buffer

maxBufferBytes caps everything waiting to be delivered. That is the number to provision against; the SDK evicts rather than exceed it. Size it for the stall you want to survive: message rate times average size times seconds. At 400 messages per second and 500 bytes each, roughly a 10,000 charger CSMS, one minute of stalled delivery is about 12 MB. The 32 MiB default covers about two and a half minutes. The HTTP adapters add a second, smaller cost. While a request is in flight they hold a copy of its bodies, bounded per request by maxCaptureBytes and released as soon as the exchange is captured. That scales with concurrency rather than with the buffer. Calling the capture methods yourself avoids it, since you already hold the bytes.

How delivery works

One background worker per client. It flushes when 1,000 messages are waiting or the flush interval elapses, whichever comes first, compresses the batch, and posts it.

Response	Treated as
`200`	Delivered
`400`, `401`, `413`	Permanent. Dropped immediately, never retried
`5xx`, network error, timeout	Retried with jittered backoff, five attempts, 500ms up to 30s

Retries are not configurable. An SDK on a customer hot path that retries aggressively against a struggling API turns a partial outage into a full one. Under sustained failure the buffer fills and the SDK evicts its own oldest captures. It never applies backpressure to your service.

Is it working?

stats() is a snapshot of the client’s delivery counters. It is always available, including on an inert or closed client, and each counter maps to one root cause.

s := panda.Stats()
// {Captured:40120 DroppedInvalid:0 DroppedOversize:0 DroppedEvicted:9402
//  DroppedUndeliverable:0 DroppedFault:0 BufferedMessages:2 BufferBytes:528}

const s = panda.stats();
// { captured: 40120, droppedInvalid: 0, droppedOversize: 0, droppedEvicted: 9402,
//   droppedUndeliverable: 0, droppedFault: 0, bufferedMessages: 2, bufferBytes: 528 }

s = panda.stats()
# Stats(captured=40120, dropped_invalid=0, dropped_oversize=0, dropped_evicted=9402,
#       dropped_undeliverable=0, dropped_fault=0, buffered_messages=2, buffer_bytes=528)

Counter	What it tells you
`captured` is 0	The capture path is not wired in, or the client is inert
`droppedInvalid`	Identity resolution is failing
`droppedOversize`	Bodies exceed `maxCaptureBytes`
`droppedEvicted`	Upstream cannot keep up, or the buffer is undersized
`droppedUndeliverable`	Network, API key, or ingestion fault
`droppedFault`	A bug in the SDK. Please report it

It is a pull based snapshot, so it feeds Prometheus, OpenTelemetry, or a log line without the SDK depending on any of them.

prometheus.MustRegister(prometheus.NewCounterFunc(opts, func() float64 {
    return float64(panda.Stats().DroppedEvicted)
}))

Logging

The SDK reports problems to your logger by default, at a bounded rate: at most one summary line per minute, and nothing at all while healthy.

evpanda: captures dropped window=60s captured=12 invalid_identity=148302 buffered=0 buffer_bytes=0

Mode	Output
`silent`	Nothing. Counters still work
`errors`	Default. Config problems at startup, plus the per minute summary
`debug`	Adds per batch delivery failures and a summary on close

Set logMode in config, or EVPANDA_LOG=silent|errors|debug in the environment to change it without a code change. Config wins over the environment.

Shutdown

Stop accepting traffic first, then drain.

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

await server.close();
if (!(await panda.close())) {
  log.warn("evpanda: shut down with messages still buffered");
}

server.shutdown()
if not panda.close():
    log.warning("evpanda: shut down with messages still buffered")

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

Go. Shutdown(ctx) uses your context deadline, Close() uses DrainTimeout. Both return ErrDrainIncomplete if the deadline passed with messages still buffered.
Node. close(timeoutMs?) resolves to whether it drained. The flush timer is unref’d, so it never holds your process open, which also means an unclosed client loses what it captured since the last flush.
Python. close(timeout=None) returns whether it drained. Clients are context managers, a client the host never closes is drained at interpreter exit, and a client inherited across fork() restarts its delivery thread in the child.

flush() forces an immediate delivery and waits for it. It blocks for as long as the transport retries take, so use it at shutdown or while debugging, never on a request path.

Troubleshooting

Nothing arrives and captured is 0

Either the client is inert or the capture calls are not running.Check the startup fault. Confirm EVPANDA_API_KEY is set in the environment your service actually runs in; set in your shell but absent from the container is the classic miss.

Nothing arrives and droppedInvalid is climbing

Identity resolution is failing. This is the most common integration fault.For OCPI, check that something is actually stamping the partner: setIdentity on the request, use_identity around the call, the context, or a resolver. See Identity.

Nothing arrives and droppedUndeliverable is climbing

Capture works, delivery does not. Check egress:

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 key, an OCPI client a roaming network key.

Messages deliver but do not show up

The ingestion API validates each message independently and drops what fails, after returning success. The usual causes, in order:

An OCPP message with no tenant pair. The API requires it even though the SDKs treat it as optional.
An OCPI exchange with no status code. It must be 100 to 599.
An identity field over its limit. Tenant name is 32 characters, the rest are 64.

droppedOversize is high

A body or frame over maxCaptureBytes, 64 KiB by default, drops the whole message. Raise the cap; 256 KiB is reasonable for a roaming server carrying large location or CDR payloads. Raise the buffer ceiling with it.

Memory grew after adding the SDK

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

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

OCPP server

The full integration in Go, Node, and Python.

OCPI server

The same, plus the HTTP adapters.

Core concepts

SDK integration

Getting started

OCPP server

OCPI server

Install

Get an API key

Start a client

A bad config never crashes your boot

Configuration

Sizing the buffer

How delivery works

Is it working?

Logging

Shutdown

Troubleshooting

Next

OCPP server

OCPI server

OCPP server

OCPI server

​Install

​Get an API key

​Start a client

​A bad config never crashes your boot

​Configuration

​Sizing the buffer

​How delivery works

​Is it working?

​Logging

​Shutdown

​Troubleshooting

​Next

OCPP server

OCPI server

Install

Get an API key

Start a client

A bad config never crashes your boot

Configuration

Sizing the buffer

How delivery works

Is it working?

Logging

Shutdown

Troubleshooting

Next