arkyn
ChangelogGuides
docs / services / log-service

LogService

The LogService is a static singleton service for configuring log ingestion endpoints. It stores the traffic source identifier, service token, and API URL used by Arkyn's logging system to send logs to a centralized server.

Import

ts

import { LogService } from "@arkyn/server/logService";
Learn how subpath and root imports differ in How do I use imports.

Methods

setConfig(config) - Sets the log service configuration (only once, subsequent calls are ignored, see Notes below). As of v3.0.12, throws if neither serviceToken nor the deprecated userToken alias is provided.
getConfig() - Returns the current configuration or undefined if not set. As of v3.0.9, apiUrl on the returned object is string | null, it's null when no valid, secure endpoint has been configured. See Breaking Changes. As of v3.0.12, the returned object's key is serviceToken (previously userToken).
resetConfig() - Resets the stored configuration, allowing a new initialization.

Configuration options

  • trafficSourceId (required): A string identifier for the traffic source, as defined in your Arkyn dashboard. This helps categorize and filter logs by source.
  • serviceToken (required): A string token for authenticating log submissions. Renamed from userToken in v3.0.12 to make explicit that it must be a static, application-level credential (for example an environment variable set once at app boot), never a per-request or per-session value: because setConfig() only ever honors its first call, passing a per-request token would leak whichever request configured the service first into every subsequent request's outbound telemetry for the life of the process.
  • userToken (optional, deprecated): the previous name for serviceToken. Still works exactly the same way, but logs a dev-mode warning via flushDebugLogs when used. If both are passed, serviceToken wins and no warning is logged.
  • logBaseApiUrl (optional): A custom base URL for the log ingestion API. Must be an https:// URL, or http://localhost/http://127.0.0.1 for local development, any other http:// URL is rejected (a warning is emitted via flushDebugLogs, and no apiUrl is set). As of v3.0.9, there is no default log server, if logBaseApiUrl is omitted or rejected, apiUrl is null and no log requests are made.

Usage example

typescript

import { LogService } from "@arkyn/server/logService";


// Configure the log service (typically in your app's entry point)
LogService.setConfig({
    trafficSourceId: "your-traffic-source-id",
    serviceToken: "your-service-token",
});


// With custom API URL
LogService.setConfig({
    trafficSourceId: "your-traffic-source-id",
    serviceToken: "your-service-token",
    logBaseApiUrl: "https://custom-log-server.com",
});


// Check current configuration
const config = LogService.getConfig();
if (config?.apiUrl) {
    console.log(config.apiUrl); // Full API URL for log ingestion, or null if not configured
    console.log(config.trafficSourceId);
    console.log(config.serviceToken);
}


// Reset configuration (useful for testing)
LogService.resetConfig();

Integration with ApiService

When using ApiService with route variables (:param syntax), the logging system can better aggregate and categorize your API calls:

typescript

import { ApiService } from "@arkyn/server/apiService";
import { LogService } from "@arkyn/server/logService";


// Configure logging
LogService.setConfig({
    trafficSourceId: "my-app-traffic-source",
    serviceToken: "auth-token",
});


const api = new ApiService({
    baseUrl: "https://api.example.com",
    enableDebug: true,
});


// Using route variables helps the log system group requests
await api.get("/users/:userId", { urlParams: { userId: "123" } });
await api.get("/users/:userId", { urlParams: { userId: "456" } });
// Logs are grouped under "/users/:userId" instead of separate entries
Logs are also not sent when NODE_ENV is "development", even if setConfig() was called correctly, keep this in mind when testing locally, as submitted logs won't appear until you run in a non-development environment.

Notes

The setConfig method is designed to be called once during application initialization. Subsequent calls still leave the first configuration in place (it's a singleton), but as of v3.0.12 they now also log a dev-mode warning via flushDebugLogs instead of failing silently, so an accidental reconfiguration attempt is visible during development.
As of v3.0.9, there is no default log server. If logBaseApiUrl is omitted, or set to an insecure http:// URL other than localhost/127.0.0.1, apiUrl is null and the logging system makes no network calls at all, it fails closed instead of silently sending logs to a hardcoded endpoint. See Breaking Changes.
When apiUrl is set, it includes the full ingestion endpoint path (/ingest-log).
As of v3.0.9, requestHeaders, requestBody, responseHeaders, and responseBody are redacted with parseSensitiveData before being sent to the log endpoint (Authorization, Cookie/Set-Cookie, password, token/refreshToken/accessToken, apiKey, secret, matched case-insensitively).
Use resetConfig() primarily for testing scenarios where you need to reconfigure the service between test cases.
Related in Services
On this page
    arkyn