Ignore certain route handlers (eg healthcheck)

[alexandr2110pro]

I've got an app deployed to AWS ECS and every request to /health/status (required by the load balancer's target group) emit trace spans (every n sec). Very annoying.

Please either allow ignoring them on @vercel/otel level or provide a comprehensive guide on filtering them out in the collector config yaml file.

[alexandr2110pro]

I've tried this:

// sampler.ts
import type { Attributes } from '@opentelemetry/api';
import {
  AlwaysOnSampler,
  type Sampler,
  SamplingDecision,
  type SamplingResult,
} from '@opentelemetry/sdk-trace-node';
import { ATTR_HTTP_ROUTE } from '@opentelemetry/semantic-conventions';

export class NextJSSampler implements Sampler {
  static readonly DEFAULT_IGNORE_PATTERNS = [
    /^\/_next\//,
    /^\/images\//,
    // /\?_rsc=/,
    /^\/health/,
  ];

  private readonly baseSampler: Sampler;
  private readonly ingnorePatterns: RegExp[];

  constructor(props: { base?: Sampler; ignorePatterns?: RegExp[] } = {}) {
    this.baseSampler = props.base ?? new AlwaysOnSampler();

    this.ingnorePatterns =
      props.ignorePatterns || NextJSSampler.DEFAULT_IGNORE_PATTERNS;
  }

  shouldSample(...args: Parameters<Sampler['shouldSample']>): SamplingResult {
    const attributes: Attributes = args[4];
    const route =
      this.getNextRoute(attributes) ?? this.getHttpRoute(attributes);

    return this.isIgnoredRoute(route)
      ? { decision: SamplingDecision.NOT_RECORD }
      : this.baseSampler.shouldSample(...args);
  }

  private isIgnoredRoute(route?: string): boolean {
    if (!route) return false;
    return !!this.ingnorePatterns.find(re => re.test(route));
  }

  private getNextRoute(attributes: Attributes): string | undefined {
    const value = attributes['next.route'];
    if (typeof value === 'string') return value;
    return undefined;
  }

  private getHttpRoute(attributes: Attributes): string | undefined {
    const value = attributes[ATTR_HTTP_ROUTE];
    if (typeof value === 'string') return value;
    return undefined;
  }

  toString(): string {
    return 'Next JS Sampler - Exclude Health Route';
  }
}

and used it like this:

// instrumentation.ts
import { ParentBasedSampler } from '@opentelemetry/sdk-trace-node';
import { registerOTel } from '@vercel/otel';

import { NextJSSampler } from '@com/shared-otel';

export function register() {
  registerOTel({
    traceSampler: new ParentBasedSampler({
      root: new NextJSSampler(),
    }),
  });
}

but I still see traces for /health/status/route

[alexandr2110pro]

After a little more digging, I've found that at the moment of execution of the trace sampler, only a few attributes are set

{
    "next.span_name": "GET /health/status",
    "next.span_type": "BaseServer.handleRequest",
    "http.method": "GET",
    "http.target": "/health/status"
}

and http.target is deprecated at otel semantic conventions

[alexandr2110pro]

This code does the job:

import type { Attributes } from '@opentelemetry/api';
import {
  AlwaysOnSampler,
  type Sampler,
  SamplingDecision,
  type SamplingResult,
} from '@opentelemetry/sdk-trace-node';
import {
  ATTR_HTTP_ROUTE,
  SEMATTRS_HTTP_TARGET,
} from '@opentelemetry/semantic-conventions';

export class NextJSSampler implements Sampler {
  static readonly DEFAULT_IGNORE_PATTERNS = [
    /^\/_next\//,
    /^\/images\//,
    // /\?_rsc=/,
    /^\/health/,
  ];

  private readonly baseSampler: Sampler;
  private readonly ignorePatterns: RegExp[];

  constructor(props: { base?: Sampler; ignorePatterns?: RegExp[] } = {}) {
    this.baseSampler = props.base ?? new AlwaysOnSampler();

    this.ignorePatterns =
      props.ignorePatterns || NextJSSampler.DEFAULT_IGNORE_PATTERNS;
  }

  shouldSample(...args: Parameters<Sampler['shouldSample']>): SamplingResult {
    const attributes: Attributes = args[4];

    // TODO: keep an eye on https://github.com/vercel/otel/issues/143#issue-2874289175
    const route =
      // this is not populated at the moment of execution of the sampler
      this.getNextRoute(attributes) ??
      // this is not populated at the moment of execution of the sampler
      this.getHttpRoute(attributes) ??
      // this is populated
      this.getHttpTarget(attributes);

    return this.isIgnoredRoute(route)
      ? { decision: SamplingDecision.NOT_RECORD }
      : this.baseSampler.shouldSample(...args);
  }

  private isIgnoredRoute(route?: string): boolean {
    if (!route) return false;
    return this.ignorePatterns.some(re => re.test(route));
  }

  private getNextRoute(attributes: Attributes): string | undefined {
    const value = attributes['next.route'];
    if (typeof value === 'string') return value;
    return undefined;
  }

  private getHttpRoute(attributes: Attributes): string | undefined {
    const value = attributes[ATTR_HTTP_ROUTE];
    if (typeof value === 'string') return value;
    return undefined;
  }

  private getHttpTarget(attributes: Attributes): string | undefined {
    // TODO: replace SEMATTRS_HTTP_TARGET when better alternative is available
    //       https://github.com/vercel/otel/issues/143#issuecomment-2678223912
    const value = attributes[SEMATTRS_HTTP_TARGET];
    if (typeof value === 'string') return value;
    return undefined;
  }

  toString(): string {
    return 'Next JS Sampler - Exclude Health Route';
  }
}

then in instrumentation.ts:

import {
  ConsoleSpanExporter,
  ParentBasedSampler,
  TraceIdRatioBasedSampler,
} from '@opentelemetry/sdk-trace-node';
import { registerOTel } from '@vercel/otel';

import { NextJSSampler } from '@com/shared-otel';

export function register() {
  registerOTel({
    traceSampler: new ParentBasedSampler({
      root: new NextJSSampler({
        // or any other sampler. 
        base: new TraceIdRatioBasedSampler(0.1),
      }),
    }),
  });
}

---

However, due to the issues explained above, it doesn't seem to be the 100% correct approach.
I think it would be much better if the conventional, not deprecated, attributes were populated before executing the sampler.

Dear maintainers, is it the intended behavior or not?
If not, could you point me in the direction of solving it correctly so I can dive deeper and contribute a PR?