Skip to content
Effect V4 Docs

DevToolsSchema.ts

DevToolsSchema.ts overview

Section titled “DevToolsSchema.ts overview”

Defines the experimental wire schema used by the Effect devtools protocol.

The module contains the serialized message shapes exchanged between devtools clients and servers: span snapshots, span events, metric snapshots, heartbeats, and request/response unions. Use these schemas at protocol boundaries to encode, decode, or validate custom transports that need to interoperate with the built-in unstable devtools client and server.

Since v4.0.0

Exports Grouped by Category

Section titled “Exports Grouped by Category”

schemas

Section titled “schemas”

Counter

Section titled “Counter”

Schema for a counter metric snapshot, including the count and whether updates are incremental.

Signature

declare const Counter: Schema.Struct<{
  readonly id: Schema.String
  readonly type: Schema.tag<"Counter">
  readonly description: Schema.UndefinedOr<Schema.String>
  readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
  readonly state: Schema.Struct<{
    readonly count: Schema.Union<readonly [Schema.Number, Schema.BigInt]>
    readonly incremental: Schema.Boolean
  }>
}>

Source

Since v4.0.0

Counter (type alias)

Section titled “Counter (type alias)”

Type of a devtools counter metric snapshot.

Details

The state contains the current count and whether the counter reports incremental updates.

Signature

type Counter = Schema.Schema.Type<typeof Counter>

Source

Since v4.0.0

ExternalSpan

Section titled “ExternalSpan”

Schema for an external parent span context containing span id, trace id, and sampling flag.

Signature

declare const ExternalSpan: Schema.Codec<ExternalSpan, ExternalSpan, never, never>

Source

Since v4.0.0

ExternalSpan (interface)

Section titled “ExternalSpan (interface)”

Serialized parent span context for a span created outside the current devtools span tree.

Signature

export interface ExternalSpan {
  readonly _tag: "ExternalSpan"
  readonly spanId: string
  readonly traceId: string
  readonly sampled: boolean
}

Source

Since v4.0.0

Frequency

Section titled “Frequency”

Schema for a devtools frequency metric snapshot.

Details

The metric state records occurrence counts by string key.

Signature

declare const Frequency: Schema.Struct<{
  readonly id: Schema.String
  readonly type: Schema.tag<"Frequency">
  readonly description: Schema.UndefinedOr<Schema.String>
  readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
  readonly state: Schema.Struct<{ readonly occurrences: Schema.$ReadonlyMap<Schema.String, Schema.Number> }>
}>

Source

Since v4.0.0

Frequency (type alias)

Section titled “Frequency (type alias)”

Type of a devtools frequency metric snapshot.

Details

The state maps observed string values to occurrence counts.

Signature

type Frequency = Schema.Schema.Type<typeof Frequency>

Source

Since v4.0.0

Gauge

Section titled “Gauge”

Schema for a devtools gauge metric snapshot.

Details

The metric state contains the current numeric or bigint value.

Signature

declare const Gauge: Schema.Struct<{
  readonly id: Schema.String
  readonly type: Schema.tag<"Gauge">
  readonly description: Schema.UndefinedOr<Schema.String>
  readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
  readonly state: Schema.Struct<{ readonly value: Schema.Union<readonly [Schema.Number, Schema.BigInt]> }>
}>

Source

Since v4.0.0

Gauge (type alias)

Section titled “Gauge (type alias)”

Type of a devtools gauge metric snapshot.

Details

The state contains the current numeric or bigint value.

Signature

type Gauge = Schema.Schema.Type<typeof Gauge>

Source

Since v4.0.0

Histogram

Section titled “Histogram”

Schema for a devtools histogram metric snapshot.

Details

The metric state includes bucket counts plus the total count, minimum, maximum, and sum.

Signature

declare const Histogram: Schema.Struct<{
  readonly id: Schema.String
  readonly type: Schema.tag<"Histogram">
  readonly description: Schema.UndefinedOr<Schema.String>
  readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
  readonly state: Schema.Struct<{
    readonly buckets: Schema.$Array<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>
    readonly count: Schema.Number
    readonly min: Schema.Number
    readonly max: Schema.Number
    readonly sum: Schema.Number
  }>
}>

Source

Since v4.0.0

Histogram (type alias)

Section titled “Histogram (type alias)”

Type of a devtools histogram metric snapshot.

Details

The state includes bucket counts plus the total count, minimum, maximum, and sum.

Signature

type Histogram = Schema.Schema.Type<typeof Histogram>

Source

Since v4.0.0

Metric

Section titled “Metric”

Schema for any devtools metric snapshot.

Details

Accepted metric kinds are counters, frequencies, gauges, histograms, and summaries.

Signature

declare const Metric: Schema.Union<
  readonly [
    Schema.Struct<{
      readonly id: Schema.String
      readonly type: Schema.tag<"Counter">
      readonly description: Schema.UndefinedOr<Schema.String>
      readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
      readonly state: Schema.Struct<{
        readonly count: Schema.Union<readonly [Schema.Number, Schema.BigInt]>
        readonly incremental: Schema.Boolean
      }>
    }>,
    Schema.Struct<{
      readonly id: Schema.String
      readonly type: Schema.tag<"Frequency">
      readonly description: Schema.UndefinedOr<Schema.String>
      readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
      readonly state: Schema.Struct<{ readonly occurrences: Schema.$ReadonlyMap<Schema.String, Schema.Number> }>
    }>,
    Schema.Struct<{
      readonly id: Schema.String
      readonly type: Schema.tag<"Gauge">
      readonly description: Schema.UndefinedOr<Schema.String>
      readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
      readonly state: Schema.Struct<{ readonly value: Schema.Union<readonly [Schema.Number, Schema.BigInt]> }>
    }>,
    Schema.Struct<{
      readonly id: Schema.String
      readonly type: Schema.tag<"Histogram">
      readonly description: Schema.UndefinedOr<Schema.String>
      readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
      readonly state: Schema.Struct<{
        readonly buckets: Schema.$Array<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>
        readonly count: Schema.Number
        readonly min: Schema.Number
        readonly max: Schema.Number
        readonly sum: Schema.Number
      }>
    }>,
    Schema.Struct<{
      readonly id: Schema.String
      readonly type: Schema.tag<"Summary">
      readonly description: Schema.UndefinedOr<Schema.String>
      readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
      readonly state: Schema.Struct<{
        readonly quantiles: Schema.$Array<Schema.Tuple<readonly [Schema.Number, Schema.UndefinedOr<Schema.Number>]>>
        readonly count: Schema.Number
        readonly min: Schema.Number
        readonly max: Schema.Number
        readonly sum: Schema.Number
      }>
    }>
  ]
>

Source

Since v4.0.0

Metric (type alias)

Section titled “Metric (type alias)”

Type of any devtools metric snapshot.

Details

The union covers counters, frequencies, gauges, histograms, and summaries.

Signature

type Metric = Schema.Schema.Type<typeof Metric>

Source

Since v4.0.0

MetricLabel

Section titled “MetricLabel”

Schema for a metric label key/value pair in a devtools metrics snapshot.

Signature

declare const MetricLabel: Schema.Struct<{ readonly key: Schema.String; readonly value: Schema.String }>

Source

Since v4.0.0

MetricLabel (type alias)

Section titled “MetricLabel (type alias)”

Type of a metric label key/value pair in a devtools metrics snapshot.

Signature

type MetricLabel = Schema.Schema.Type<typeof MetricLabel>

Source

Since v4.0.0

MetricsRequest

Section titled “MetricsRequest”

Schema for a devtools request asking the client to send a metrics snapshot.

Signature

declare const MetricsRequest: Schema.Struct<{ readonly _tag: Schema.tag<"MetricsRequest"> }>

Source

Since v4.0.0

MetricsRequest (type alias)

Section titled “MetricsRequest (type alias)”

Type of a devtools request asking the client to send a metrics snapshot.

Signature

type MetricsRequest = Schema.Schema.Type<typeof MetricsRequest>

Source

Since v4.0.0

MetricsSnapshot

Section titled “MetricsSnapshot”

Schema for a devtools protocol message containing the current metric snapshots.

Signature

declare const MetricsSnapshot: Schema.Struct<{
  readonly _tag: Schema.tag<"MetricsSnapshot">
  readonly metrics: Schema.$Array<
    Schema.Union<
      readonly [
        Schema.Struct<{
          readonly id: Schema.String
          readonly type: Schema.tag<"Counter">
          readonly description: Schema.UndefinedOr<Schema.String>
          readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
          readonly state: Schema.Struct<{
            readonly count: Schema.Union<readonly [Schema.Number, Schema.BigInt]>
            readonly incremental: Schema.Boolean
          }>
        }>,
        Schema.Struct<{
          readonly id: Schema.String
          readonly type: Schema.tag<"Frequency">
          readonly description: Schema.UndefinedOr<Schema.String>
          readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
          readonly state: Schema.Struct<{ readonly occurrences: Schema.$ReadonlyMap<Schema.String, Schema.Number> }>
        }>,
        Schema.Struct<{
          readonly id: Schema.String
          readonly type: Schema.tag<"Gauge">
          readonly description: Schema.UndefinedOr<Schema.String>
          readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
          readonly state: Schema.Struct<{ readonly value: Schema.Union<readonly [Schema.Number, Schema.BigInt]> }>
        }>,
        Schema.Struct<{
          readonly id: Schema.String
          readonly type: Schema.tag<"Histogram">
          readonly description: Schema.UndefinedOr<Schema.String>
          readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
          readonly state: Schema.Struct<{
            readonly buckets: Schema.$Array<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>
            readonly count: Schema.Number
            readonly min: Schema.Number
            readonly max: Schema.Number
            readonly sum: Schema.Number
          }>
        }>,
        Schema.Struct<{
          readonly id: Schema.String
          readonly type: Schema.tag<"Summary">
          readonly description: Schema.UndefinedOr<Schema.String>
          readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
          readonly state: Schema.Struct<{
            readonly quantiles: Schema.$Array<Schema.Tuple<readonly [Schema.Number, Schema.UndefinedOr<Schema.Number>]>>
            readonly count: Schema.Number
            readonly min: Schema.Number
            readonly max: Schema.Number
            readonly sum: Schema.Number
          }>
        }>
      ]
    >
  >
}>

Source

Since v4.0.0

MetricsSnapshot (type alias)

Section titled “MetricsSnapshot (type alias)”

Type of a devtools protocol message containing the current metric snapshots.

Signature

type MetricsSnapshot = Schema.Schema.Type<typeof MetricsSnapshot>

Source

Since v4.0.0

ParentSpan

Section titled “ParentSpan”

Schema for a span parent, either a full devtools Span payload or an ExternalSpan context.

Signature

declare const ParentSpan: Schema.Union<
  readonly [Schema.Codec<Span, Span, never, never>, Schema.Codec<ExternalSpan, ExternalSpan, never, never>]
>

Source

Since v4.0.0

ParentSpan (type alias)

Section titled “ParentSpan (type alias)”

Type of a span parent, represented either by a devtools Span payload or an ExternalSpan context.

Signature

type ParentSpan = Span | ExternalSpan

Source

Since v4.0.0

Ping

Section titled “Ping”

Schema for the devtools heartbeat request sent by the client.

Signature

declare const Ping: Schema.Struct<{ readonly _tag: Schema.tag<"Ping"> }>

Source

Since v4.0.0

Ping (type alias)

Section titled “Ping (type alias)”

Type of the devtools heartbeat request sent by the client.

Signature

type Ping = Schema.Schema.Type<typeof Ping>

Source

Since v4.0.0

Pong

Section titled “Pong”

Schema for the devtools heartbeat response.

Signature

declare const Pong: Schema.Struct<{ readonly _tag: Schema.tag<"Pong"> }>

Source

Since v4.0.0

Pong (type alias)

Section titled “Pong (type alias)”

Type of the devtools heartbeat response.

Signature

type Pong = Schema.Schema.Type<typeof Pong>

Source

Since v4.0.0

Request

Section titled “Request”

Schema for devtools protocol requests accepted by the server.

Details

Requests include heartbeat pings, spans, span events, and metric snapshots.

Signature

declare const Request: Schema.Union<
  readonly [
    Schema.Struct<{ readonly _tag: Schema.tag<"Ping"> }>,
    Schema.Codec<Span, Span, never, never>,
    Schema.Struct<{
      readonly _tag: Schema.tag<"SpanEvent">
      readonly traceId: Schema.String
      readonly spanId: Schema.String
      readonly name: Schema.String
      readonly startTime: Schema.BigInt
      readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.Any>>
    }>,
    Schema.Struct<{
      readonly _tag: Schema.tag<"MetricsSnapshot">
      readonly metrics: Schema.$Array<
        Schema.Union<
          readonly [
            Schema.Struct<{
              readonly id: Schema.String
              readonly type: Schema.tag<"Counter">
              readonly description: Schema.UndefinedOr<Schema.String>
              readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
              readonly state: Schema.Struct<{
                readonly count: Schema.Union<readonly [Schema.Number, Schema.BigInt]>
                readonly incremental: Schema.Boolean
              }>
            }>,
            Schema.Struct<{
              readonly id: Schema.String
              readonly type: Schema.tag<"Frequency">
              readonly description: Schema.UndefinedOr<Schema.String>
              readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
              readonly state: Schema.Struct<{ readonly occurrences: Schema.$ReadonlyMap<Schema.String, Schema.Number> }>
            }>,
            Schema.Struct<{
              readonly id: Schema.String
              readonly type: Schema.tag<"Gauge">
              readonly description: Schema.UndefinedOr<Schema.String>
              readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
              readonly state: Schema.Struct<{ readonly value: Schema.Union<readonly [Schema.Number, Schema.BigInt]> }>
            }>,
            Schema.Struct<{
              readonly id: Schema.String
              readonly type: Schema.tag<"Histogram">
              readonly description: Schema.UndefinedOr<Schema.String>
              readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
              readonly state: Schema.Struct<{
                readonly buckets: Schema.$Array<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>
                readonly count: Schema.Number
                readonly min: Schema.Number
                readonly max: Schema.Number
                readonly sum: Schema.Number
              }>
            }>,
            Schema.Struct<{
              readonly id: Schema.String
              readonly type: Schema.tag<"Summary">
              readonly description: Schema.UndefinedOr<Schema.String>
              readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
              readonly state: Schema.Struct<{
                readonly quantiles: Schema.$Array<
                  Schema.Tuple<readonly [Schema.Number, Schema.UndefinedOr<Schema.Number>]>
                >
                readonly count: Schema.Number
                readonly min: Schema.Number
                readonly max: Schema.Number
                readonly sum: Schema.Number
              }>
            }>
          ]
        >
      >
    }>
  ]
>

Source

Since v4.0.0

Request (type alias)

Section titled “Request (type alias)”

Type of devtools protocol requests accepted by the server.

Details

Requests include heartbeat pings, spans, span events, and metric snapshots.

Signature

type Request = Schema.Schema.Type<typeof Request>

Source

Since v4.0.0

Response

Section titled “Response”

Schema for devtools protocol responses sent by the server.

Details

Responses include heartbeat pongs and requests for metric snapshots.

Signature

declare const Response: Schema.Union<
  readonly [
    Schema.Struct<{ readonly _tag: Schema.tag<"Pong"> }>,
    Schema.Struct<{ readonly _tag: Schema.tag<"MetricsRequest"> }>
  ]
>

Source

Since v4.0.0

Response (type alias)

Section titled “Response (type alias)”

Type of devtools protocol responses sent by the server.

Details

Responses include heartbeat pongs and requests for metric snapshots.

Signature

type Response = Schema.Schema.Type<typeof Response>

Source

Since v4.0.0

Span

Section titled “Span”

Schema for an Effect span telemetry payload sent to devtools.

Signature

declare const Span: Schema.Codec<Span, Span, never, never>

Source

Since v4.0.0

Span (interface)

Section titled “Span (interface)”

Telemetry payload for an Effect span sent to devtools, including identity, attributes, status, sampling flag, and optional parent span.

Signature

export interface Span {
  readonly _tag: "Span"
  readonly spanId: string
  readonly traceId: string
  readonly name: string
  readonly sampled: boolean
  readonly attributes: ReadonlyMap<string, unknown>
  readonly status: SpanStatus
  readonly parent: Option.Option<ParentSpan>
}

Source

Since v4.0.0

SpanEvent

Section titled “SpanEvent”

Schema for a named event emitted by a span, including trace id, span id, start time, and optional attributes.

Signature

declare const SpanEvent: Schema.Struct<{
  readonly _tag: Schema.tag<"SpanEvent">
  readonly traceId: Schema.String
  readonly spanId: Schema.String
  readonly name: Schema.String
  readonly startTime: Schema.BigInt
  readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.Any>>
}>

Source

Since v4.0.0

SpanEvent (type alias)

Section titled “SpanEvent (type alias)”

Type of a named event emitted by a span and sent to devtools.

Signature

type SpanEvent = Schema.Schema.Type<typeof SpanEvent>

Source

Since v4.0.0

SpanStatus

Section titled “SpanStatus”

Schema for devtools span status, either started or ended.

Signature

declare const SpanStatus: Schema.Union<
  readonly [
    Schema.Struct<{ readonly _tag: Schema.tag<"Started">; readonly startTime: Schema.BigInt }>,
    Schema.Struct<{
      readonly _tag: Schema.tag<"Ended">
      readonly startTime: Schema.BigInt
      readonly endTime: Schema.BigInt
      readonly exit: Schema.decodeTo<
        Schema.Exit<Schema.Unknown, Schema.Unknown, Schema.Unknown>,
        Schema.Exit<Schema.Void, Schema.Defect, Schema.Defect>,
        never,
        never
      >
    }>
  ]
>

Source

Since v4.0.0

SpanStatus (type alias)

Section titled “SpanStatus (type alias)”

Type of a devtools span status, either started or ended.

Signature

type SpanStatus = Schema.Schema.Type<typeof SpanStatus>

Source

Since v4.0.0

SpanStatusEnded

Section titled “SpanStatusEnded”

Schema for a span status representing an ended span, including start time, end time, and encoded exit status. Encoding drops success values with Exit.asVoid.

Signature

declare const SpanStatusEnded: Schema.Struct<{
  readonly _tag: Schema.tag<"Ended">
  readonly startTime: Schema.BigInt
  readonly endTime: Schema.BigInt
  readonly exit: Schema.decodeTo<
    Schema.Exit<Schema.Unknown, Schema.Unknown, Schema.Unknown>,
    Schema.Exit<Schema.Void, Schema.Defect, Schema.Defect>,
    never,
    never
  >
}>

Source

Since v4.0.0

SpanStatusEnded (type alias)

Section titled “SpanStatusEnded (type alias)”

Type of a span status representing an ended span with start time, end time, and exit status.

Signature

type SpanStatusEnded = Schema.Schema.Type<typeof SpanStatusEnded>

Source

Since v4.0.0

SpanStatusStarted

Section titled “SpanStatusStarted”

Schema for a span status representing a span that has started but not yet ended.

Signature

declare const SpanStatusStarted: Schema.Struct<{
  readonly _tag: Schema.tag<"Started">
  readonly startTime: Schema.BigInt
}>

Source

Since v4.0.0

SpanStatusStarted (type alias)

Section titled “SpanStatusStarted (type alias)”

Type of a span status representing a span that has started but not yet ended.

Signature

type SpanStatusStarted = Schema.Schema.Type<typeof SpanStatusStarted>

Source

Since v4.0.0

Summary

Section titled “Summary”

Schema for a devtools summary metric snapshot.

Details

The metric state contains quantile values plus the total count, minimum, maximum, and sum.

Signature

declare const Summary: Schema.Struct<{
  readonly id: Schema.String
  readonly type: Schema.tag<"Summary">
  readonly description: Schema.UndefinedOr<Schema.String>
  readonly attributes: Schema.UndefinedOr<Schema.$Record<Schema.String, Schema.String>>
  readonly state: Schema.Struct<{
    readonly quantiles: Schema.$Array<Schema.Tuple<readonly [Schema.Number, Schema.UndefinedOr<Schema.Number>]>>
    readonly count: Schema.Number
    readonly min: Schema.Number
    readonly max: Schema.Number
    readonly sum: Schema.Number
  }>
}>

Source

Since v4.0.0

Summary (type alias)

Section titled “Summary (type alias)”

Type of a devtools summary metric snapshot.

Details

The state contains quantile values plus the total count, minimum, maximum, and sum.

Signature

type Summary = Schema.Schema.Type<typeof Summary>

Source

Since v4.0.0

utils

Section titled “utils”

Request (namespace)

Section titled “Request (namespace)”

Namespace containing helper types for devtools protocol requests.

Source

Since v4.0.0

WithoutPing (type alias)

Section titled “WithoutPing (type alias)”

Devtools request messages excluding heartbeat pings.

Details

DevToolsServer handles Ping internally and exposes only these requests to client handlers.

Signature

type WithoutPing = Exclude<Request, { readonly _tag: "Ping" }>

Source

Since v4.0.0

Response (namespace)

Section titled “Response (namespace)”

Namespace containing helper types for devtools protocol responses.

Source

Since v4.0.0

WithoutPong (type alias)

Section titled “WithoutPong (type alias)”

Devtools response messages excluding heartbeat pongs.

Details

DevToolsServer sends Pong internally and accepts only these responses from client handlers.

Signature

type WithoutPong = Exclude<Response, { readonly _tag: "Pong" }>

Source

Since v4.0.0