Documentation
¶
Overview ¶
Package sparkplugb holds what the edge, host and app packages of this Sparkplug B module share: the Logger and FieldLogger they log through and the RetryPolicy, such as ExponentialBackoff, that decides reconnection.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ExponentialBackoff ¶
type ExponentialBackoff struct {
// Initial is the delay after the first failure; 500 ms when zero.
Initial time.Duration
// Max caps the delay; 30 s when zero.
Max time.Duration
// Attempts is the number of retries; 5 when zero, unbounded when
// negative.
Attempts int
// NoJitter waits the delay itself, for tests.
NoJitter bool
}
ExponentialBackoff is the RetryPolicy that retries after a delay that doubles from Initial up to Max, with jitter: the wait is drawn at random between half of the delay and the delay, so that devices that failed together do not come back together.
The zero value retries up to 5 times from 500 ms (Attempts 5, Initial 500 ms, Max 30 s).
func (ExponentialBackoff) Delay ¶
func (b ExponentialBackoff) Delay(attempt int) time.Duration
Delay returns the wait after the failure of attempt, regardless of the error and of Attempts.
func (ExponentialBackoff) ShouldRetry ¶
ShouldRetry implements RetryPolicy.
type FieldLogger ¶
type FieldLogger interface {
Logger
With(kv ...any) FieldLogger
}
FieldLogger is a Logger that keeps fields (key-value pairs) with its lines: With returns one that adds kv to every line. The packages of this module name themselves (component=edge, ...) through it when a Logger is one.
func NewSlogLogger ¶
func NewSlogLogger(h slog.Handler) FieldLogger
NewSlogLogger returns a FieldLogger that writes to the slog handler h, at the slog levels of the same names.
func NewStdLogger ¶
func NewStdLogger(l *log.Logger, debug bool) FieldLogger
NewStdLogger returns a Logger that writes to l (the standard logger when nil), with the level in front of each line, from Info up; NewStdLogger with debug true writes Debug lines too.
type Logger ¶
type Logger interface {
Debugf(format string, args ...any)
Infof(format string, args ...any)
Warnf(format string, args ...any)
Errorf(format string, args ...any)
}
Logger receives the log of the edge nodes, host applications and applications of this module: set it as the Logger of their configuration. A nil Logger logs nothing. Debug is the detail of every publish and subscribe; Info, what changes (a state transition, a rebirth); Warn, what failed and is retried; Error, what fails a call or stops work.
A Logger is called from many goroutines, and must not block.
func ComponentLogger ¶
ComponentLogger returns the Logger a package of this module uses for l: NopLogger for nil, and for a FieldLogger one with component=name.
type RetryPolicy ¶
RetryPolicy decides whether a failed connection or publish is made again, and when: the edge nodes, host applications and applications of this module take one for their reconnection. attempt is the number of the attempt that failed, from 0. A policy is called from many goroutines.
type SessionChecks ¶ added in v0.5.0
type SessionChecks uint8
SessionChecks selects stricter checks that a host application (package host) or an application (package app) makes on the data messages of an edge node around its NBIRTH, to drop a message of the session that ended instead of applying it to the new one. The zero value makes none: that is the default, and what Sparkplug B 3.0 asks for.
Sparkplug carries no session in NDATA and DDATA, and MQTT orders messages per topic only, so a broker may deliver a message of the ending session among those of the new one (go-sparkplugb#24, LIMITATIONS.md). Without these checks two such messages are applied to the new session; each check drops one of them, at the cost of dropping valid messages of edge nodes that do not meet its assumption. A dropped message of the new session leaves a gap in its sequence, and the gap costs a rebirth. Births and deaths are never dropped by these checks.
Use them only for edge nodes whose payload timestamp is the time of publishing, from a clock that does not go back, and that stamp no birth before the NBIRTH it follows, as this module's edge package does. host.Config and app.Config take them for every edge node (SessionChecks) or per edge node (SessionChecksFor).
const ( // CheckBirthMillisecond drops an NDATA or DDATA that arrived before the // NBIRTH of its edge node and is stamped in the millisecond of that // NBIRTH, or was applied before it with that timestamp. By default it is // taken for the new session's: births and the data right after them share // a millisecond. With this check, a new-session NDATA or DDATA stamped in // the NBIRTH's millisecond that the broker delivers before the NBIRTH is // dropped. CheckBirthMillisecond SessionChecks = 1 << iota // CheckOlderInSequence drops an NDATA or DDATA that carries the sequence // number the session expects next but is stamped before the session's // NBIRTH, within 30 s of that NBIRTH. By default a message in sequence is // applied whatever its timestamp. With this check, data of an edge node // that stamps a payload earlier than its time of publishing (the time a // value was sampled, say) or whose clock goes back is dropped after each // NBIRTH. CheckOlderInSequence // SessionChecksAll is every check. SessionChecksAll = CheckBirthMillisecond | CheckOlderInSequence )
type SessionDropMetrics ¶ added in v0.5.0
type SessionDropMetrics interface {
OnSessionDrop(groupID, edgeNodeID, messageType string)
}
SessionDropMetrics is implemented by the Metrics of a host or application that counts the data messages and births it drops as belonging to a session that has ended: those published before the current NBIRTH and out of sequence, which are always dropped, and those the SessionChecks drop. OnSessionDrop is called with the edge node and the message type (NDATA, DDATA, DBIRTH or DDEATH), with none of the runtime's locks held.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package app implements a Sparkplug B Application that is not a Primary Host: it subscribes to the spBv1.0 namespace, tracks edge nodes and devices, resolves metric aliases and sends NCMD/DCMD commands, but never publishes STATE.
|
Package app implements a Sparkplug B Application that is not a Primary Host: it subscribes to the spBv1.0 namespace, tracks edge nodes and devices, resolves metric aliases and sends NCMD/DCMD commands, but never publishes STATE. |
|
Package edge implements a Sparkplug B Edge Node: the NBIRTH/NDEATH and DBIRTH/DDEATH lifecycle with bdSeq and seq numbering, data publishing, rebirth on command, and optional waiting for the Primary Host's STATE with server walking across brokers.
|
Package edge implements a Sparkplug B Edge Node: the NBIRTH/NDEATH and DBIRTH/DDEATH lifecycle with bdSeq and seq numbering, data publishing, rebirth on command, and optional waiting for the Primary Host's STATE with server walking across brokers. |
|
examples
|
|
|
aliases
command
Example: Edge Node with metric aliases for bandwidth-efficient DATA messages.
|
Example: Edge Node with metric aliases for bandwidth-efficient DATA messages. |
|
application
command
|
|
|
commands
command
Example: sending NCMD and DCMD commands from a Host Application.
|
Example: sending NCMD and DCMD commands from a Host Application. |
|
datasets
command
|
|
|
edge-node
command
|
|
|
host-app
command
|
|
|
server-walking
command
|
|
|
templates
command
|
|
|
Package host implements a Sparkplug B Primary Host Application: it publishes STATE birth and death certificates, keeps a registry of edge nodes and devices, validates seq ordering with reordering and rebirth requests, and sends NCMD/DCMD commands.
|
Package host implements a Sparkplug B Primary Host Application: it publishes STATE birth and death certificates, keeps a registry of edge nodes and devices, validates seq ordering with reordering and rebirth requests, and sends NCMD/DCMD commands. |
|
internal
|
|
|
callback
Package callback is how the runtimes of this module call the application's code: the callbacks of their Config, Metrics, the Logger, a BdSeqStore and a RetryPolicy.
|
Package callback is how the runtimes of this module call the application's code: the callbacks of their Config, Metrics, the Logger, a BdSeqStore and a RetryPolicy. |
|
Package mqtt defines the Transport interface through which the edge, host and app packages use an MQTT broker, and PahoTransport, its implementation on the Eclipse Paho client.
|
Package mqtt defines the Transport interface through which the edge, host and app packages use an MQTT broker, and PahoTransport, its implementation on the Eclipse Paho client. |
|
Package payload builds, encodes and decodes Sparkplug B Protobuf payloads: metrics with typed values and aliases, properties, data sets, templates, quality, and the bdSeq and rebirth control metrics.
|
Package payload builds, encodes and decodes Sparkplug B Protobuf payloads: metrics with typed values and aliases, properties, data sets, templates, quality, and the bdSeq and rebirth control metrics. |
|
Package topic parses and builds Sparkplug B topic names in the spBv1.0 namespace: message types (NBIRTH, DDATA, NCMD, ...), edge node and device topics, and the STATE topic of a host application.
|
Package topic parses and builds Sparkplug B topic names in the spBv1.0 namespace: message types (NBIRTH, DDATA, NCMD, ...), edge node and device topics, and the STATE topic of a host application. |