hellhound/telemetry

Typed Hellhound events, as sinal descriptors over :telemetry.

Every event carries closed, non-secret values only: no token, code, state, nonce, verifier, secret, claim, identity, query string, header or body ever reaches an event. Each carries the correlation that the caller set with hellhound.with_correlation, which Hellhound also passes to its HTTP Gun requests.

Event	When
`[hellhound, http, request]` (`http_request`)	an outbound provider request completes or fails
`[hellhound, login]` (`login`)	`complete_login` or `recover_custody` returns
`[hellhound, refresh]` (`refresh`)	a refresh completes, joins another, or fails
`[hellhound, logout]` (`logout`)	`logout` ends a session

sinal.observe(telemetry.http_request(), fn(measurements, request) {
  // measurements.duration_ms, request.host, request.outcome, ...
  Nil
})

Types

Evidence

</>

Whether a failed request may have reached the provider.

pub type Evidence {
  NotSent
  MaybeSent
}

Constructors

```
NotSent
```
Proven not sent.
```
MaybeSent
```
May have been sent.

HttpMeasurements

</>

pub type HttpMeasurements {
  HttpMeasurements(duration_ms: Int)
}

Constructors

```
HttpMeasurements(duration_ms: Int)
```

HttpMethod

</>

pub type HttpMethod {
  Get
  Post
}

Constructors

```
Get
```
```
Post
```

HttpRequest

</>

[hellhound, http, request] metadata: discovery, keys, token, userinfo, introspection and revocation requests. Queries are never recorded.

pub type HttpRequest {
  HttpRequest(
    method: HttpMethod,
    host: String,
    path: String,
    outcome: Outcome,
    correlation: option.Option(correlation.Correlation),
  )
}

Constructors

HttpRequest(
  method: HttpMethod,
  host: String,
  path: String,
  outcome: Outcome,
  correlation: option.Option(correlation.Correlation),
)

</>

[hellhound, login] metadata.

pub type Login {
  Login(
    outcome: LoginOutcome,
    correlation: option.Option(correlation.Correlation),
  )
}

Constructors

Login(
  outcome: LoginOutcome,
  correlation: option.Option(correlation.Correlation),
)

LoginOutcome

</>

pub type LoginOutcome {
  LoginSucceeded
  LoginCallbackRefused
  LoginDenied
  LoginExchangeFailed
  LoginIdentityRejected
  LoginCustodyUnconfirmed
  LoginUnavailable
}

Constructors

```
LoginSucceeded
```
A session was installed.
```
LoginCallbackRefused
```
The callback was malformed, unbound to this browser, replayed or expired; nothing was sent.
```
LoginDenied
```
The provider denied the authorization.
```
LoginExchangeFailed
```
The code exchange failed or its outcome is unknown.
```
LoginIdentityRejected
```
Tokens arrived but the identity was not accepted.
```
LoginCustodyUnconfirmed
```
Installation was not confirmed; a recovery value was returned.
```
LoginUnavailable
```
A store did not answer, or the login timed out before the exchange.

Logout

</>

[hellhound, logout] metadata: emitted once custody is removed.

pub type Logout {
  Logout(
    revocation: Revocation,
    correlation: option.Option(correlation.Correlation),
  )
}

Constructors

Logout(
  revocation: Revocation,
  correlation: option.Option(correlation.Correlation),
)

Outcome

</>

A response status, or a failure with its submission evidence.

pub type Outcome {
  Status(code: Int)
  Failed(evidence: Evidence, reason: TransportReason)
}

Constructors

```
Status(code: Int)
```

Failed(evidence: Evidence, reason: TransportReason)

Refresh

</>

[hellhound, refresh] metadata.

pub type Refresh {
  Refresh(
    outcome: RefreshOutcome,
    correlation: option.Option(correlation.Correlation),
  )
}

Constructors

Refresh(
  outcome: RefreshOutcome,
  correlation: option.Option(correlation.Correlation),
)

RefreshOutcome

</>

pub type RefreshOutcome {
  Refreshed
  RefreshJoined
  RefreshNotSent
  RefreshRejected
  RefreshRevoked
  RefreshQuarantined
  RefreshWaitTimedOut
  RefreshUnconfirmed
  RefreshUnavailable
}

Constructors

```
Refreshed
```
This request refreshed the session.
```
RefreshJoined
```
Another request’s refresh was waited for and used.
```
RefreshNotSent
```
Proven not sent; the generation was released.
```
RefreshRejected
```
Rejected before grant processing; the generation was released.
```
RefreshRevoked
```
The refresh token is revoked (invalid_grant).
```
RefreshQuarantined
```
The generation is quarantined after an uncertain outcome.
```
RefreshWaitTimedOut
```
Another request’s refresh did not settle within the wait.
```
RefreshUnconfirmed
```
Publication was not confirmed; a recovery value was returned.
```
RefreshUnavailable
```
The custody store did not answer.

Revocation

</>

pub type Revocation {
  Revoked
  RevocationUnsupported
  RevocationFailed
  RevocationSkipped
}

Constructors

```
Revoked
```
```
RevocationUnsupported
```
```
RevocationFailed
```
```
RevocationSkipped
```

SessionMeasurements

</>

pub type SessionMeasurements {
  SessionMeasurements(duration_ms: Int)
}

Constructors

```
SessionMeasurements(duration_ms: Int)
```

TransportReason

</>

The closed transport failure reasons, as hellhound.TransportReason names them. May gain variants as HTTP Gun does.

pub type TransportReason {
  DestinationRejected
  InsecureScheme
  InvalidDestination
  ResolutionFailed
  ConnectionRefused
  ConnectionFailed
  TlsRejected
  Timeout
  ResponseTooLarge
  ResponseHeadersTooLarge
  MalformedHttp
  ReceiveFailed
  UnsupportedContentEncoding
  OtherTransportFailure
}

Constructors

```
DestinationRejected
```
```
InsecureScheme
```
```
InvalidDestination
```
```
ResolutionFailed
```
```
ConnectionRefused
```
```
ConnectionFailed
```
```
TlsRejected
```
```
Timeout
```
```
ResponseTooLarge
```
```
ResponseHeadersTooLarge
```
```
MalformedHttp
```
```
ReceiveFailed
```
```
UnsupportedContentEncoding
```
```
OtherTransportFailure
```

Values

http_request

</>

pub fn http_request() -> sinal.Event(
  HttpMeasurements,
  HttpRequest,
)

The descriptor for [hellhound, http, request]. On the wire the metadata is #{method => <<"get">> | <<"post">>, host => Binary, path => Binary, outcome => {status, Code} | {failure, not_sent | maybe_sent, Reason}, correlation => Binary} (correlation omitted when unset) and the measurements are #{duration_ms => Integer}.

</>

pub fn login() -> sinal.Event(SessionMeasurements, Login)

The descriptor for [hellhound, login]; outcome is a snake_case binary.

login_outcomes

</>

pub const login_outcomes: List(LoginOutcome)

logout

</>

pub fn logout() -> sinal.Event(SessionMeasurements, Logout)

The descriptor for [hellhound, logout]; revocation is a snake_case binary.

refresh

</>

pub fn refresh() -> sinal.Event(SessionMeasurements, Refresh)

The descriptor for [hellhound, refresh]; outcome is a snake_case binary.

refresh_outcomes

</>

pub const refresh_outcomes: List(RefreshOutcome)

revocations

</>

pub const revocations: List(Revocation)

transport_reason_name

</>

pub fn transport_reason_name(reason: TransportReason) -> String

The snake_case wire name of a transport reason.

transport_reasons

</>

pub const transport_reasons: List(TransportReason)

Every transport reason, for codecs and tests.