@temporalio/worker
Version:
Temporal.io SDK Worker sub-package
334 lines (332 loc) • 12.2 kB
TypeScript
import { native } from '@temporalio/core-bridge';
import { Logger, LogLevel } from '@temporalio/common';
import { Duration } from '@temporalio/common/lib/time';
/**
* Options used to create a Temporal Runtime.
* These are mostly about logging and telemetry configuration.
*/
export interface RuntimeOptions {
/**
* A logger that will receive log messages emitted by the SDK, as well as through the
* [Workflow](https://typescript.temporal.io/api/namespaces/workflow#log) and
* [Activity](https://typescript.temporal.io/api/namespaces/activity#log) context loggers.
*
* By default, the Runtime's logger outputs everything to stderr, filtering out
* messages below the `INFO` level. To customize this behavior, instantiate a
* {@link DefaultLogger} with a different log level and a custom output function. Refer to
* [this sample](https://github.com/temporalio/samples-typescript/tree/main/hello-world/src/sample.ts)
* for an example.
*
* Note that by default, log messages emitted from the native side of the SDK are printed directly
* to the console, _independently of `RuntimeOptions.logger`_ – that is, this option only applies
* to log messages emitted from the TS side of the SDK. See {@link TelemetryOptions.logging} on
* how to turn on forwarding of native logs to the TS logger.
*/
logger?: Logger;
/**
* Options for Core-side telemetry, including logs and metrics.
*/
telemetryOptions?: TelemetryOptions;
/**
* Automatically shutdown workers on any of these signals.
*
* @default
* ```ts
* ['SIGINT', 'SIGTERM', 'SIGQUIT', 'SIGUSR2']
* ```
*/
shutdownSignals?: NodeJS.Signals[];
}
export interface TelemetryOptions {
/**
* A string in the env filter format specified here:
* https://docs.rs/tracing-subscriber/0.2.20/tracing_subscriber/struct.EnvFilter.html
*
* Which determines what tracing data is collected in the Core SDK.
*
* @deprecated Use `logging.filter` instead
*/
tracingFilter?: string;
/**
* If set to `true`, do not prefix metrics with `temporal_`.
*
* @deprecated Use `metrics.metricPrefix` instead
*/
noTemporalPrefixForMetrics?: boolean;
/**
* Control where to send log messages emitted by native code.
*
* ### Log Forwarding
*
* By default, logs emitted by the native side of the SDK are printed directly to the console,
* _independently of `RuntimeOptions.logger`_. To enable forwarding of those logs messages to the
* TS side logger, add the `forward` property to the `logging` object.
*
* For example:
*
* ```ts
* Runtime.install({
* logger: new DefaultLogger('INFO'),
* telemetryOptions: {
* logging: {
* filter: { core: 'INFO', other: 'WARN' },
* forward: {},
* },
* },
* });
* ```
*
* Note that forwarded log messages are internally throttled/buffered for a few milliseconds to
* reduce overhead incurred by Rust-to-JS calls. In rare cases, this may result in log messages
* appearing out of order by a few milliseconds. Users are discouraged from using log forwarding
* with verboseness sets to `DEBUG` or `TRACE`.
*/
logging?: LogExporterConfig;
/**
* Control exporting {@link NativeConnection} and {@link Worker} metrics.
*
* Turned off by default.
*/
metrics?: MetricsExporterConfig;
/**
* @deprecated Core SDK tracing is no longer supported. This option is ignored.
*/
tracing?: unknown;
}
/**
* Configuration for logs emitted by the native side of the SDK.
*
* @see {@link TelemetryOptions.logging}
*/
export type LogExporterConfig = {
/**
* Determines the verboseness of log output emitted by the native side of the SDK.
*
* This can be specified either as an (env filter format)[https://docs.rs/tracing-subscriber/0.2.20/tracing_subscriber/struct.EnvFilter.html]
* string, or as a {@link CoreLogFilterOptions} object.
*
* Note that if log forwarding is enabled, then the configured {@link Runtime.logger}
* may apply further filtering on top of this.
*
* **BACKWARD COMPATIBILITY**
*
* If `logging.filter` is missing, the following legacy values (if present) will be used instead (in the given order):
* - {@link ForwardLogger.forward.level} => `makeTelemetryFilterString({ core: level, other: level })`
* - {@link TelemetryOptions.tracingFilter}
* - Default value of `makeTelemetryFilterString({ core: 'WARN', other: 'ERROR'})`
*
* @default
* `{ core: 'WARN', other: 'ERROR'}` (with some exceptions, as described in backward compatibility note above).
*/
filter?: string | CoreLogFilterOptions;
} & Partial<ConsoleLogger | ForwardLogger>;
/**
* Log directly to console
*/
export interface ConsoleLogger {
console: {};
}
/**
* Forward logs to {@link Runtime} logger
*/
export interface ForwardLogger {
forward: {
/**
* What level, if any, logs should be forwarded from core at
*
* @deprecated Use {@link TelemetryOptions.logging.filter} instead
*/
level?: LogLevel;
};
}
/**
* Options for configuring the verboseness of log output emitted by the native side of the SDK.
*/
export interface CoreLogFilterOptions {
/**
* Determines which level of verbosity to keep for _SDK Core_'s related events.
* Any event with a verbosity level less than that value will be discarded.
* Possible values are, in order: 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR'.
*/
core: LogLevel;
/**
* Determines which level of verbosity to keep for events related to third
* party native packages imported by SDK Core. Any event with a verbosity level
* less than that value will be discarded. Possible values are, in order:
* 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR'.
*
* @defaults `'ERROR'`.
*/
other?: LogLevel;
}
/**
* Configuration for exporting metrics emitted by Core.
*/
export type MetricsExporterConfig = {
/**
* Determines if the metrics exporter should use cumulative or delta temporality.
* Only applies to OpenTelemetry exporter.
*
* @deprecated Use 'otel.temporality' instead
*/
temporality?: 'cumulative' | 'delta';
/**
* A prefix to add to all metrics.
*
* @default 'temporal_'
*/
metricPrefix?: string;
/**
* Tags to add to all metrics emitted by the worker.
*/
globalTags?: Record<string, string>;
/**
* Whether to put the service_name on every metric.
*
* @default true
*/
attachServiceName?: boolean;
} & (PrometheusMetricsExporter | OtelCollectorExporter);
/**
* OpenTelemetry Collector options for exporting metrics or traces
*/
export interface OtelCollectorExporter {
otel: {
/**
* URL of a gRPC OpenTelemetry collector.
*
* Syntax generally looks like `http://server:4317` or `grpc://server:4317` for OTLP/gRPC exporters,
* or `http://server:4318/v1/metrics` for OTLP/HTTP exporters. Make sure to set the `http` option
* to `true` for OTLP/HTTP endpoints.
*
* @format Starts with "grpc://" or "http://" for an unsecured connection (typical),
* or "grpcs://" or "https://" for a TLS connection.
* @note The `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable, if set, will override this property.
*/
url: string;
/**
* If set to true, the exporter will use OTLP/HTTP instead of OTLP/gRPC.
*
* @default false meaning that the exporter will use OTLP/gRPC.
*/
http?: boolean;
/**
* Optional set of HTTP request headers to send to Collector (e.g. for authentication)
*/
headers?: Record<string, string>;
/**
* Specify how frequently in metrics should be exported.
*
* @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
* @default 1 second
*/
metricsExportInterval?: Duration;
/**
* If set to true, the exporter will use seconds for durations instead of milliseconds.
*
* @default false
*/
useSecondsForDurations?: boolean;
/**
* Determines if the metrics exporter should use cumulative or delta temporality.
* See the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/ce50e4634efcba8da445cc23523243cb893905cb/specification/metrics/datamodel.md#temporality)
* for more information.
*
* @default 'cumulative'
*/
temporality?: 'cumulative' | 'delta';
/**
* Overrides boundary values for histogram metrics.
*
* The key is the metric name and the value is the list of bucket boundaries.
*
* For example:
*
* ```
* {
* "request_latency": [1, 5, 10, 25, 50, 100, 250, 500, 1000],
* }
* ```
*
* The metric name will apply regardless of name prefixing.
*
* See [this doc](https://docs.rs/opentelemetry_sdk/latest/opentelemetry_sdk/metrics/enum.Aggregation.html#variant.ExplicitBucketHistogram.field.boundaries)
* for the exact meaning of boundaries.
*/
histogramBucketOverrides?: Record<string, number[]>;
};
}
/**
* Prometheus metrics exporter options
*/
export interface PrometheusMetricsExporter {
prometheus: {
/**
* Address to bind the Prometheus HTTP metrics exporter server
* (for example, `0.0.0.0:1234`).
*
* Metrics will be available for scraping under the standard `/metrics` route.
*/
bindAddress: string;
/**
* If set to true, all counter names will include a "_total" suffix.
*
* @default false
*/
countersTotalSuffix?: boolean;
/**
* If set to true, all histograms will include the unit in their name as a suffix.
* EX: "_milliseconds"
*
* @default false
*/
unitSuffix?: boolean;
/**
* If set to true, the exporter will use seconds for durations instead of milliseconds.
*
* @default false
*/
useSecondsForDurations?: boolean;
/**
* Overrides boundary values for histogram metrics.
*
* The key is the metric name and the value is the list of bucket boundaries.
*
* For example:
*
* ```
* {
* "request_latency": [1, 5, 10, 25, 50, 100, 250, 500, 1000],
* }
* ```
*
* The metric name will apply regardless of name prefixing.
*
* See [this doc](https://docs.rs/opentelemetry_sdk/latest/opentelemetry_sdk/metrics/enum.Aggregation.html#variant.ExplicitBucketHistogram.field.boundaries)
* for the exact meaning of boundaries.
*/
histogramBucketOverrides?: Record<string, number[]>;
};
}
/**
* @hidden
* @internal
*/
export interface CompiledRuntimeOptions {
shutdownSignals: NodeJS.Signals[];
telemetryOptions: native.RuntimeOptions;
logger: Logger;
}
export declare function compileOptions(options: RuntimeOptions): CompiledRuntimeOptions;
/**
* @deprecated Use {@link CoreLogFilterOptions} instead.
*/
export type MakeTelemetryFilterStringOptions = CoreLogFilterOptions;
/**
* A helper to build a filter string for use in `RuntimeOptions.telemetryOptions.tracingFilter`.
*
* Note that one may instead simply pass a {@link CoreLogFilterOptions} object directly to
* `RuntimeOptions.telemetryOptions.logging.filter`. This function may however still be useful
* in some particular use cases and will therefore be kept around.
*/
export declare function makeTelemetryFilterString(options: CoreLogFilterOptions): string;