relay/telemetry

The Sinal telemetry events Relay emits, as descriptors a handler attaches to with sinal.observe.

Event	When
`[relay, frame, rejected]`	a transport refused a frame before admission
`[relay, request, admitted]`	the server admitted a request
`[relay, invocation, started]`	a handler started
`[relay, invocation, completed]`	a handler returned; measures `duration_ms`
`[relay, invocation, cancelled]`	a running handler was cancelled
`[relay, invocation, crashed]`	a handler crashed or timed out
`[relay, exchange, closed]`	an exchange closed
`[relay, http, rejected]`	the HTTP endpoint refused a request
`[relay, authorization, decided]`	bearer admission granted or refused a request
`[relay, client, call]`	a client request finished; measures `duration_ms`

Server events carry the method, the tool name when there is one, the request’s sinal/correlation, and the listener label set with relay/http.with_label or relay/runtime.with_label. Every request has a correlation, and all of its server events, exchange.closed included, carry the same one: the endpoint’s relay/http.with_correlation value, else the one the client sent (a Relay client sends its relay/client.with_correlation), else a fresh one. So every record’s correlation field is a Correlation, written with sinal/correlation.required_field(); a client event carries the correlation of its call, which a view without one mints. Only frame.rejected, for a frame refused before admission, has no correlation field. Read metadata by label: a later release may add fields. Status and reason fields are enums, never prose.

import gleam/io
import gleam/option
import relay/telemetry
import sinal

pub fn log_tools() -> sinal.Attachment {
  use _measured, meta <- sinal.observe(telemetry.invocation_started_event())
  case meta.tool {
    option.Some(name) -> io.println("tool " <> name)
    option.None -> Nil
  }
}

Types

AuthorizationDecidedMeta

</>

Metadata of [relay, authorization, decided].

pub type AuthorizationDecidedMeta {
  AuthorizationDecidedMeta(
    verifier: String,
    decision: Decision,
    correlation: correlation.Correlation,
    listener: option.Option(String),
  )
}

Constructors

AuthorizationDecidedMeta(
  verifier: String,
  decision: Decision,
  correlation: correlation.Correlation,
  listener: option.Option(String),
)

CallOutcome

</>

How a client request ended.

pub type CallOutcome {
  CallCompleted
  CallToolFailed
  CallInputRequired
  CallFailed
}

Constructors

```
CallCompleted
```
```
CallToolFailed
```
```
CallInputRequired
```
```
CallFailed
```

ClientCallMeasurements

</>

Measurements of [relay, client, call]: the request’s round trip.

pub type ClientCallMeasurements {
  ClientCallMeasurements(duration_ms: Int)
}

Constructors

ClientCallMeasurements(duration_ms: Int)

ClientCallMeta

</>

Metadata of [relay, client, call].

pub type ClientCallMeta {
  ClientCallMeta(
    method: String,
    tool: option.Option(String),
    outcome: CallOutcome,
    correlation: correlation.Correlation,
    client: option.Option(String),
  )
}

Constructors

ClientCallMeta(
  method: String,
  tool: option.Option(String),
  outcome: CallOutcome,
  correlation: correlation.Correlation,
  client: option.Option(String),
)

CrashReason

</>

Why a handler stopped without a result.

pub type CrashReason {
  HandlerCrashed
  HandlerTimedOut
}

Constructors

```
HandlerCrashed
```
```
HandlerTimedOut
```

Decision

</>

What bearer admission decided.

pub type Decision {
  Granted
  MissingToken
  InvalidToken
  VerifierUnavailable
  WrongResource
  InsufficientScope
}

Constructors

```
Granted
```
```
MissingToken
```
```
InvalidToken
```
```
VerifierUnavailable
```
```
WrongResource
```
```
InsufficientScope
```

ExchangeClosedMeta

</>

Metadata of [relay, exchange, closed].

pub type ExchangeClosedMeta {
  ExchangeClosedMeta(
    exchange_id: Int,
    correlation: correlation.Correlation,
    listener: option.Option(String),
  )
}

Constructors

ExchangeClosedMeta(
  exchange_id: Int,
  correlation: correlation.Correlation,
  listener: option.Option(String),
)

FrameProblem

</>

Why a transport refused a frame.

pub type FrameProblem {
  FrameTooLarge
  TooManyExchanges
  NestingTooDeep
  TrailingBytes
}

Constructors

```
FrameTooLarge
```
```
TooManyExchanges
```
```
NestingTooDeep
```
```
TrailingBytes
```

FrameRejectedMeta

</>

Metadata of [relay, frame, rejected].

pub type FrameRejectedMeta {
  FrameRejectedMeta(
    exchange_id: Int,
    problem: FrameProblem,
    listener: option.Option(String),
  )
}

Constructors

FrameRejectedMeta(
  exchange_id: Int,
  problem: FrameProblem,
  listener: option.Option(String),
)

HttpRejectedMeta

</>

Metadata of [relay, http, rejected].

pub type HttpRejectedMeta {
  HttpRejectedMeta(
    status: Int,
    reason: RejectReason,
    correlation: correlation.Correlation,
    listener: option.Option(String),
  )
}

Constructors

HttpRejectedMeta(
  status: Int,
  reason: RejectReason,
  correlation: correlation.Correlation,
  listener: option.Option(String),
)

InvocationCancelledMeta

</>

Metadata of [relay, invocation, cancelled].

pub type InvocationCancelledMeta {
  InvocationCancelledMeta(
    invocation_id: Int,
    method: String,
    tool: option.Option(String),
    correlation: correlation.Correlation,
    listener: option.Option(String),
  )
}

Constructors

InvocationCancelledMeta(
  invocation_id: Int,
  method: String,
  tool: option.Option(String),
  correlation: correlation.Correlation,
  listener: option.Option(String),
)

InvocationCompletedMeasurements

</>

Measurements of [relay, invocation, completed]: the handler’s run time.

pub type InvocationCompletedMeasurements {
  InvocationCompletedMeasurements(duration_ms: Int)
}

Constructors

InvocationCompletedMeasurements(duration_ms: Int)

InvocationCompletedMeta

</>

Metadata of [relay, invocation, completed].

pub type InvocationCompletedMeta {
  InvocationCompletedMeta(
    exchange_id: Int,
    invocation_id: Int,
    method: String,
    tool: option.Option(String),
    status: Status,
    correlation: correlation.Correlation,
    listener: option.Option(String),
  )
}

Constructors

InvocationCompletedMeta(
  exchange_id: Int,
  invocation_id: Int,
  method: String,
  tool: option.Option(String),
  status: Status,
  correlation: correlation.Correlation,
  listener: option.Option(String),
)

InvocationCrashedMeta

</>

Metadata of [relay, invocation, crashed].

pub type InvocationCrashedMeta {
  InvocationCrashedMeta(
    invocation_id: Int,
    method: String,
    tool: option.Option(String),
    reason: CrashReason,
    correlation: correlation.Correlation,
    listener: option.Option(String),
  )
}

Constructors

InvocationCrashedMeta(
  invocation_id: Int,
  method: String,
  tool: option.Option(String),
  reason: CrashReason,
  correlation: correlation.Correlation,
  listener: option.Option(String),
)

InvocationStartedMeta

</>

Metadata of [relay, invocation, started].

pub type InvocationStartedMeta {
  InvocationStartedMeta(
    exchange_id: Int,
    invocation_id: Int,
    method: String,
    tool: option.Option(String),
    correlation: correlation.Correlation,
    listener: option.Option(String),
  )
}

Constructors

InvocationStartedMeta(
  exchange_id: Int,
  invocation_id: Int,
  method: String,
  tool: option.Option(String),
  correlation: correlation.Correlation,
  listener: option.Option(String),
)

RejectReason

</>

Why the HTTP endpoint refused a request before the server saw it.

pub type RejectReason {
  HostNotAllowed
  OriginNotAllowed
  MethodNotAllowed
  UnsupportedMediaType
  NotAcceptable
  BodyTooLarge
  MalformedBody
  RoutingHeaderMismatch
  TooManyRequests
  TooManyStreams
  Unauthenticated
}

Constructors

```
HostNotAllowed
```
```
OriginNotAllowed
```
```
MethodNotAllowed
```
```
UnsupportedMediaType
```
```
NotAcceptable
```
```
BodyTooLarge
```
```
MalformedBody
```
```
RoutingHeaderMismatch
```
```
TooManyRequests
```
```
TooManyStreams
```
```
Unauthenticated
```

RequestAdmittedMeta

</>

Metadata of [relay, request, admitted].

pub type RequestAdmittedMeta {
  RequestAdmittedMeta(
    exchange_id: Int,
    method: String,
    correlation: correlation.Correlation,
    listener: option.Option(String),
  )
}

Constructors

RequestAdmittedMeta(
  exchange_id: Int,
  method: String,
  correlation: correlation.Correlation,
  listener: option.Option(String),
)

Status

</>

How a handler finished.

pub type Status {
  Succeeded
  ToolFailed
  InputRequested
  Failed
}

Constructors

```
Succeeded
```
```
ToolFailed
```
The tool returned an isError result.
```
InputRequested
```
The handler asked the client for another input round.
```
Failed
```
The request failed with a JSON-RPC error.

Values

authorization_decided_event

</>

pub fn authorization_decided_event() -> sinal.Event(
  Nil,
  AuthorizationDecidedMeta,
)

[relay, authorization, decided]: the verifier’s name and the decision. The token never appears.

client_call_event

</>

pub fn client_call_event() -> sinal.Event(
  ClientCallMeasurements,
  ClientCallMeta,
)

[relay, client, call], measuring the request’s round trip.

exchange_closed_event

</>

pub fn exchange_closed_event() -> sinal.Event(
  Nil,
  ExchangeClosedMeta,
)

[relay, exchange, closed].

frame_rejected_event

</>

pub fn frame_rejected_event() -> sinal.Event(
  Nil,
  FrameRejectedMeta,
)

[relay, frame, rejected].

http_rejected_event

</>

pub fn http_rejected_event() -> sinal.Event(Nil, HttpRejectedMeta)

[relay, http, rejected]: the HTTP status and why.

invocation_cancelled_event

</>

pub fn invocation_cancelled_event() -> sinal.Event(
  Nil,
  InvocationCancelledMeta,
)

[relay, invocation, cancelled].

invocation_completed_event

</>

pub fn invocation_completed_event() -> sinal.Event(
  InvocationCompletedMeasurements,
  InvocationCompletedMeta,
)

[relay, invocation, completed], measuring the handler’s run time.

invocation_crashed_event

</>

pub fn invocation_crashed_event() -> sinal.Event(
  Nil,
  InvocationCrashedMeta,
)

[relay, invocation, crashed].

invocation_started_event

</>

pub fn invocation_started_event() -> sinal.Event(
  Nil,
  InvocationStartedMeta,
)

[relay, invocation, started]. tool names the tool of a tools/call.

request_admitted_event

</>

pub fn request_admitted_event() -> sinal.Event(
  Nil,
  RequestAdmittedMeta,
)

[relay, request, admitted].