What causes "serviceName is required" in Unitech/pm2?

Pass serviceName in the tracing options (a stable identifier for your service).

Unitech/pm2 · error · Error

serviceName is required

Error message

serviceName is required

What it means

The BPM tracing feature's getTracer() returns an OpenTelemetry tracer that must be labeled with a serviceName — the identity of the instrumented service. Without serviceName, spans have no service identity, so the method throws to prevent emitting unattributed telemetry.

Solutions

Pass serviceName in the tracing options (a stable identifier for your service).
Set it at init, e.g. apm.init({ tracing: { serviceName: 'my-api' } }).

Example fix

// before
apm.init({ tracing: { enabled: true } });
// after
apm.init({ tracing: { enabled: true, serviceName: 'my-api' } });

Defensive patterns

Strategy: validation

Validate before calling

if (!tracingOpts || typeof tracingOpts.serviceName !== 'string' || !tracingOpts.serviceName.trim()) {
  throw new Error('serviceName is required for OpenTelemetry tracing');
}

Type guard

const hasServiceName = (o) => Boolean(o && typeof o.serviceName === 'string' && o.serviceName.trim());

Try / catch

try {
  const tracer = apm.getTracer();
} catch (e) {
  if (/serviceName is required/.test(e.message)) {
    apm.options.serviceName = process.env.npm_package_name || 'default-service';
    tracer = apm.getTracer();
  } else throw e;
}

Prevention

Set serviceName at agent init, sourced from package.json name or an env var.
Treat serviceName as required config for any service emitting traces.

When it happens

Trigger: Calling getTracer() (or enabling OTel tracing) without setting serviceName in the tracing options.

Common situations: Enabling tracing with a partial config; forgetting the serviceName key when initializing the agent; copying a config sample that omitted it.

Related errors

AI-assisted analysis of Unitech/pm2@31adee8048 (2026-08-13). Data as JSON: /api/errors/ed2b1f0d4a31c79f. Report an issue: GitHub.

Appendix: source

Thrown at modules/pm2-io-bpm/features/tracing.js:139

                return false
              }
              return this.options.ignoreOutgoingUrls.some((matcher) => applyMatcher(matcher, request))
            }
          }
        })
      ]
    })

    this.otel.start()

    Configuration.configureModule({
      otel_tracing: true
    })
  }

  getTracer () {
    if (!this.options.serviceName) {
      throw new Error('serviceName is required')
    }
    const { trace } = require('@opentelemetry/api')
    return trace.getTracer(this.options.serviceName)
  }

  destroy () {
    if (!this.otel) return
    this.logger('stop otel tracer')
    this.otel.shutdown()

    Configuration.configureModule({
      otel_tracing: false
    })
  }
}

function applyMatcher (matcher, request) {
  if (!matcher) {

View on GitHub (pinned to 31adee8048)