Shared Memory Sizing

API7 Gateway data plane nodes keep several kinds of cross-worker state in NGINX shared memory zones (lua_shared_dict). Most of these behave like caches: when they fill up, the least recently used entries are evicted and the node keeps working. A few, however, hold data that grows with the size of your deployment and is not evicted — when they fill up, new writes are silently dropped. This page explains which zones to size, how much they hold, and how to change them for your scenario.

Zones That Need Sizing

The API7 Dashboard monitors the following zones because their contents are not self-healing: an overflow causes a persistent, hard-to-diagnose loss rather than a transient cache miss.

Zone	Default	Holds	Symptom when full
prometheus-metrics-advanced	256 MB	one entry per Prometheus time series	metrics stop updating; gaps in dashboards and alerts
kubernetes / nacos / consul	64 MB each	one entry per discovered service (its node list)	new or changed upstream nodes do not resolve
api-calls-for-portal	64 MB	one counter per Developer Portal API-call dimension	portal analytics under-count
tracing_buffer	32 MB	SkyWalking trace segments awaiting report	trace spans are dropped

All other shared memory zones (rate-limiting counters, EWMA balancer state, caches, and so on) evict or reset on their own and do not need tuning.

note

The defaults above are chosen to cover the majority of deployments. Change them only if your scale exceeds the capacity described below, or if you want to reclaim memory on a small deployment. An explicit value always overrides the default.

Capacity Reference

The figures below come from measuring how many entries fit per megabyte on the API7 Gateway runtime. Shared memory is allocated in fixed slab classes, so the cost per entry rounds up to the next power-of-two boundary. Crossing a boundary — a longer key or a larger value — roughly doubles the per-entry cost, which is why the numbers below step in halves.

Prometheus Metrics

Each unique metric-and-label combination (a time series) is one entry of about 256 bytes.

Zone size	Approximate time series
64 MB	260,000
256 MB (default)	1,000,000
512 MB	2,000,000

The series count grows with the number of routes and services that have the prometheus plugin enabled, multiplied by label cardinality and histogram buckets. Histogram metrics dominate: the request-latency histogram alone adds about 15 buckets per label combination, whereas counters such as bandwidth add only a couple of series each. High-cardinality labels, such as a per-upstream-node label, multiply the count quickly; use the prometheus plugin's disabled_labels metadata to drop specific labels if you need to cap it.

Service Discovery

Each discovered service is one entry whose value is the JSON list of its backend nodes, so the per-entry cost grows with the number of nodes per service.

Nodes per service	Services per 64 MB (default)
1	260,000
5	130,000
20	32,000
100	8,000

Size the kubernetes, nacos, or consul zone to the number of services in your registry, leaving headroom for the services with the largest node lists.

Developer Portal API Calls

Each entry is a counter keyed by a combination of subscription, developer, application, credential, API product, and response status — about 512 bytes.

Zone size	Approximate counter combinations
64 MB (default)	130,000
128 MB	260,000

The number of live combinations grows with portal consumers × applications × products × distinct response codes. Counters are flushed periodically, so size for peak concurrent cardinality rather than cumulative traffic.

Tracing Buffer

The buffer holds SkyWalking trace segments queued for reporting. It absorbs spikes when the collector is slow or briefly unreachable; segments drain as they are reported.

Segment size	Segments per 32 MB (default)
~1 KB	16,000
~2 KB	8,000
~4 KB	4,000

Size this for how long you need to keep buffering during a collector slowdown, not for steady-state throughput. If you see dropped segments while the collector is healthy, raise it.

Change the Defaults

Override any of these zones on the data plane. The value is a size string such as 128m or 1g. For Helm deployments, apply the change with helm upgrade; for a directly managed data plane, edit config.yaml and restart the node. Shared memory zones are sized once at startup, so the new size takes effect only after a full restart — a reload does not resize them.

Data Plane Config

Set the zone under nginx_config in the data plane config.yaml, which overrides config-default.yaml:

nginx_config:
  meta:
    lua_shared_dict:
      prometheus-metrics: 512m      # backs the prometheus-metrics-advanced zone
  http:
    lua_shared_dict:
      tracing_buffer: 64m
      api-calls-for-portal: 128m
    custom_lua_shared_dict:
      kubernetes: 128m
      nacos: 128m
      consul: 128m

Helm

Set the zone in the gateway chart values:

apisix:
  meta:
    luaSharedDict:
      prometheus-metrics: 512m      # backs the prometheus-metrics-advanced zone
  http:
    luaSharedDict:
      tracing_buffer: 64m
      api-calls-for-portal: 128m
  customLuaSharedDicts:
    - name: kubernetes
      size: 128m
    - name: nacos
      size: 128m
    - name: consul
      size: 128m

The Prometheus zone is configured under the meta context with the key prometheus-metrics, which sizes the prometheus-metrics-advanced zone shown on the Dashboard.

Monitor Usage

The API7 Dashboard reports the used and total capacity of each monitored zone per data plane node and raises an alert as a zone approaches its limit. Use it to confirm your sizing under real traffic and to catch a zone trending toward full before it starts dropping data.