feat(grpc): native multi-backend failover via grpc-js (#144)

Support a comma-separated list in SW_AGENT_COLLECTOR_BACKEND_SERVICES so the
agent fails over between OAP backends, implemented with grpc-js's own resolver
and load balancing rather than an application-level channel state machine.

Transport
- A single address keeps the built-in `dns:` resolver, so one hostname with
  multiple A/AAAA records is load-balanced and periodically re-resolved.
- Multiple addresses register a small `sw-static` resolver (the built-in
  `ipv4:`/`ipv6:` schemes accept IP literals only) and use `pick_first` with
  `shuffleAddressList`, which spreads agents across backends while keeping the
  channel authority stable.
- Reconnection uses grpc-js exponential backoff (1s to 30s); the agent no longer
  polls channel state or re-selects backends itself.
- No client keepalive: the agent's own reporting traffic is the liveness signal,
  and a stock OAP (grpc-java defaults) answers unsolicited pings with
  GOAWAY ENHANCE_YOUR_CALM.
- Retry is scoped to ManagementService/reportInstanceProperties, the only
  idempotent unary call. Trace and meter uploads are never retried at the gRPC
  layer, so a replayed stream cannot duplicate segments.

Reporting semantics
- Best effort: a failed report discards its batch and is never re-sent, so
  statistics cannot be double-counted. Discards are logged with a running total.
- flush() is a bounded single attempt, not a delivery guarantee. It forces out
  pending data first (which has not been attempted yet), then waits on any prior
  in-flight report with the remaining budget, so a stuck RPC cannot stall a host
  such as AWS Lambda.
- Authentication failures keep the channel and emit a throttled error pointing at
  SW_AGENT_AUTHENTICATION; switching backends cannot fix a cluster-wide token.
- A backend that is reachable but unresponsive is not failed over: failover
  targets unreachable backends, not functional health.

Behavior changes
- Host http_proxy/https_proxy no longer affect the OAP uplink
  (grpc.enable_http_proxy=0); agent to OAP via HTTP proxy is not supported.
- Default SW_AGENT_LOGGING_LEVEL is now `warn`, so connection and data-loss
  diagnostics are visible without extra configuration.
- Under TLS, all backends must present certificates sharing SANs because
  verification follows the channel authority; one DNS name with multiple records
  is preferred for HA.

Docs and tests
- docs/en/setup/configuration.md and docs/en/advanced/troubleshooting.md cover the
  address forms, the diagnostics and the best-effort contract.
- Unit tests for the resolver, channel manager, report coalescing and both senders,
  plus a remote-e2e case that stops the active mock collector and asserts reporting
  continues on the standby.

No new configuration options are introduced.
25 files changed
tree: ddaf322ce2b5e981ded10a419ab6abf2b2ed7f1d
  1. .claude/
  2. .github/
  3. .husky/
  4. dist/
  5. docs/
  6. scripts/
  7. src/
  8. tests/
  9. .asf.yaml
  10. .dockerignore
  11. .editorconfig
  12. .eslintrc.js
  13. .file-headerrc
  14. .gitignore
  15. .gitmodules
  16. .licenserc.yaml
  17. .prettierrc
  18. CHANGELOG.md
  19. CONTRIBUTING.md
  20. jest.config.js
  21. jest.setup.js
  22. LICENSE
  23. NOTICE
  24. package-lock.json
  25. package.json
  26. README.md
  27. tsconfig.json
README.md

Apache SkyWalking Node.js Agent

The Apache SkyWalking Node.js Agent reports distributed traces and Node.js runtime metrics to an Apache SkyWalking OAP server. It instruments supported Node.js libraries without changes to their source code.

Build npm version GitHub stars

Requirements

Install

npm install skywalking-backend-js

Quick start

Start the agent before loading the modules that it must instrument:

import agent from 'skywalking-backend-js';

agent.start({
  serviceName: 'checkout-service',
  collectorAddress: '127.0.0.1:11800',
});

The same values can be set with environment variables:

export SW_AGENT_NAME=checkout-service
export SW_AGENT_COLLECTOR_BACKEND_SERVICES=127.0.0.1:11800

See Quick start for the full setup and a way to load the agent with Node.js --require.

Documentation

The documentation index includes:

  • setup and all configuration values;
  • tracing and Node.js runtime metrics;
  • supported library plugins and AWS SDK v2 behavior;
  • serverless and Webpack support;
  • build, test, plugin development, and release guides.

Main features

  • Automatic trace collection for Node.js HTTP, database, messaging, and framework libraries.
  • SkyWalking trace context transfer between supported services.
  • Twelve process-level Node.js runtime meters.
  • Optional wrappers for AWS Lambda and Azure Functions.

Contributing

Read Build and test before sending a change. Plugin authors should also read Plugin development.

Contact

  • Report Node.js Agent problems in the Apache SkyWalking issue tracker with Nodejs in the issue title.
  • Join the dev@skywalking.apache.org mailing list by sending a message to dev-subscribe@skywalking.apache.org.
  • Join the skywalking channel on Apache Slack.

License

Apache License 2.0