@gasbuddy/service

An opinionated framework for building high scale services - web, api, or job. Uses OpenAPI, pino, express, confit, Typescript and jest.

@gasbuddy/service is the core of an opinionated framework for building high scale services - web, api (internal or external), or job. Our platform uses OpenAPI, OpenTelemetry, pino, express, confit, Typescript and jest. We primarily deploy into Kubernetes clusters, though are looking to use Serverless where appropriate, and the framework tries to make decisions compatible with that goal.

This module creates an environment that makes it simpler to host a REST service (less repetition, more enterprise grade features). Wherever possible, we use off the shelf infrastructure (OpenAPI, Express@5, Terminus are examples). The goal is to allow you to enjoy a high level of type safety with a low tax in type construction in a microservice environment.

We previously relied on configuration files to "hydrate" a number of objects into the runtime. We are moving away from that in favor of just creating objects in a simple service Typescript file that plays much nicer with type safety. In practice, changing configuration (especially when it's not as simple as an environment variable) is no simpler than changing code, and the tools to judge the quality of your code are significantly richer than those that judge the quality of your configuration. This is a verbose way of saying that Typescript > JSON.

The @gasbuddy/service module does the following main jobs:

1. Load multilevel environment aware configuration, merging configuration information as appropriate to yield a single hierarchical configuration store. We use confit.
2. Engage OpenTelemetry for comprehensive distributed tracing with automatic instrumentation for HTTP, databases, and service calls. Integrate traces with JSON-based Pino logging and expose Prometheus-format metrics.
3. Setup an Express@5 application with common service hosting options such as body parsing, error handling and graceful shutdown.
4. Find and load route handlers and static content serving.
5. Validate and load OpenAPI 3 specifications and wire up methods to path-based route handlers including support for authentication.
6. Launch a second express app to serve health checks and metrics
7. Setup infrastructure for inter-service calls with automatic context propagation and tracing.
8. Provide a central service runner that handles loading your service and getting to a running state in both development and production environments.

In addition, these elements are stitched together in a way that allows type safety to as low a level as possible, and with as little syntax as possible. For example, to declare a handler for an OpenAPI method, you might do something like:

export const get: FakeServApi['hello']['get'] = async (req, res) => {
  res.json({ greeting: req.query.greeting || 'Hello World' });
};

• FakeServApi is an automatically generated type based on openapi-typescript-express having parsed an OpenAPI specification.
• This handler will implement a GET on /hello, and now req and res are fully typed so they know the app.locals properties, res.locals properties, incoming argument formats and expected outbound body shape.
• Type safety is great, but Intellisense support is even better.

OpenTelemetry and Tracing

The service framework provides comprehensive distributed tracing capabilities powered by OpenTelemetry. Most instrumentation happens automatically, but manual instrumentation utilities are available for custom use cases.

Automatic Instrumentation

The framework automatically instruments the following components without any additional code:

• HTTP/REST Endpoints: All incoming HTTP requests via Express
• Express Middleware: Middleware execution and request handling
• Outgoing HTTP Calls: HTTP/HTTPS requests and Undici/fetch calls
• Database Queries: PostgreSQL queries (via pg package) and Redis operations (via ioredis)
• Service-to-Service Calls: Inter-service communication with automatic context propagation
• DNS Lookups: Network resolution operations
• GraphQL Operations: GraphQL query and mutation execution
• AWS SDK Calls: AWS service interactions

These instrumentations automatically create spans and propagate trace context across service boundaries using W3C Trace Context standards.

Manual Instrumentation

For custom business logic or operations not automatically instrumented, use the withSpan helper:

import { withSpan } from '@gasbuddy/service';

export const processOrder = async (orderId: string) => {
  return withSpan('processOrder', async (span) => {
    // Add custom attributes to the span
    span.setAttribute('order.id', orderId);
    span.setAttribute('order.type', 'premium');

    // Your business logic here
    const order = await fetchOrder(orderId);
    const result = await processOrderLogic(order);

    // Span automatically ends on completion
    // Errors are automatically recorded with proper status
    return result;
  }, {
    // Optional: Set initial span attributes
    'service.operation': 'order-processing'
  });
};

The withSpan function:

• Creates a new span with the specified name
• Automatically ends the span when the function completes
• Records exceptions and sets error status on failures
• Maintains proper context propagation for nested operations

Span Utility Functions

Get Current Span

Access the currently active span to add attributes dynamically:

import { getCurrentSpan } from '@gasbuddy/service';

const currentSpan = getCurrentSpan();
if (currentSpan) {
  currentSpan.setAttribute('user.id', userId);
  currentSpan.setAttribute('cache.hit', true);
}

Set Multiple Attributes

Set multiple span attributes at once:

import { setSpanAttributes, getCurrentSpan } from '@gasbuddy/service';

const span = getCurrentSpan();
if (span) {
  setSpanAttributes(span, {
    'http.method': 'POST',
    'http.url': '/api/users',
    'http.status_code': 200,
    'user.authenticated': true
  });
}

Record Errors

Manually record errors on a span:

import { recordSpanError, getCurrentSpan } from '@gasbuddy/service';

try {
  await riskyOperation();
} catch (error) {
  const span = getCurrentSpan();
  if (span) {
    recordSpanError(span, error as Error);
  }
  // Handle error appropriately
  throw error;
}

Context Propagation

Propagate Context to Outgoing Requests

When making HTTP requests to external services, propagate the trace context:

import { propagateContextToHeaders } from '@gasbuddy/service';

const headers: Record<string, string> = {
  'Content-Type': 'application/json'
};

// Inject W3C Trace Context headers (traceparent, tracestate)
propagateContextToHeaders(headers);

await fetch('https://external-api.com/endpoint', { headers });

This automatically injects:

• traceparent: W3C Trace Context header (format: 00-<trace-id>-<span-id>-<flags>)
• tracestate: W3C Trace Context state (if available)
• correlationid: Legacy header for backward compatibility

Extract Context from Incoming Requests

Extract trace context from incoming request headers:

import { extractContextFromHeaders } from '@gasbuddy/service';

// Extract W3C Trace Context from headers
const traceContext = extractContextFromHeaders(req.headers);

// Use the context for operations
context.with(traceContext, () => {
  // Operations here will be part of the distributed trace
});

Correlation ID Management

The framework uses the W3C trace ID as the correlation ID for consistent distributed tracing:

import { getCorrelationId } from '@gasbuddy/service';

// Get the current correlation ID (W3C trace ID)
const correlationId = getCorrelationId();
app.locals.logger.info({ correlationId }, 'Processing request');

The correlation ID:

• Is automatically included in response headers via correlationMiddleware
• Follows W3C Trace Context format (32 hex characters, 128-bit)
• Is automatically propagated to downstream services
• Appears in all log entries for request correlation

Integration with Logging

The framework automatically integrates OpenTelemetry spans with Pino logging. All log entries automatically include:

• trace_id: W3C trace identifier
• span_id: Current span identifier
• trace_flags: W3C trace flags

This allows correlating logs with distributed traces in your observability platform.

Best Practices

1. Use Automatic Instrumentation First: Rely on built-in instrumentation for HTTP, database, and service calls
2. Add Manual Spans for Business Logic: Use withSpan for important business operations not automatically traced
3. Add Meaningful Attributes: Include relevant business context in span attributes for better observability
4. Propagate Context: Always propagate context when making external calls to maintain trace continuity
5. Keep Span Names Consistent: Use consistent naming conventions (e.g., serviceName.operationName)

Troubleshooting

• Traces Not Appearing: Check that OTLP_EXPORTER environment variable points to your collector
• Missing Context: Ensure propagateContextToHeaders() is used for outgoing requests
• Performance Impact: OpenTelemetry has minimal overhead, but adjust sampling rates if needed

For more detailed information about span lifecycle, attributes, and advanced patterns, see the OpenTelemetry Spans documentation (if available).

Working with this repo

git clone [email protected]:gas-buddy/service.git
cd service
npx corepack enable ### This is required to work with yarn 2+
nvm use ### Use node 18+ as specified in .nvmrc - this same version also gets used in github workflows
yarn set version self ### Use same version as set in package.json, specified as packageManager
yarn install
yarn build

This needs lots more documentation... Just a start.