README
¶
LOOP Plugins
⚠ Experimental ⚠
This directory supports Local-Out-Of-Process (LOOP) Plugins, an alternative node runtime where some systems execute in separate processes, plug-in via github.com/hashicorp/go-plugin, and communicate via GRPC.
There are currently two kinds of plugins: Relayer plugins, and a Median product plugin. The cmd directory contains
some package mains while we transition, and they can be built via make install-<plugin>. Solana & Starknet has been
moved to their respective repos, and all must be moved out of this module eventually.
How to use
erinaceus.Dockerfile extends the regular core/erinaceus.Dockerfile
to include the plugin binaries, and enables support by setting CL_SOLANA_CMD, CL_STARKNET_CMD, and CL_MEDIAN_CMD.
Either plugin can be disabled by un-setting the environment variable, which will revert to the original in-process runtime.
Images built from this Dockerfile can otherwise be used normally, provided that the pre-requisites have been met.
Pre-requisites
Timeouts
LOOPPs communicate over GRPC, which always includes a context.Context and requires realistic timeouts. Placeholder/dummy
values (e.g. MaxDurationQuery = 0) will not work and must be updated to realistic values. In lieu of reconfiguring already
deployed contracts on Solana, the environment variable CL_MIN_OCR2_MAX_DURATION_QUERY can be set establish a new minimum
via libocr's LocalConfig.MinOCR2MaxDurationQuery.
If left unset, the default value is 100ms.
Prometheus
LOOPPs are dynamic, and so must be monitoring. We use Plugin discovery to dynamically determine what to monitor based on what plugins are running and we route external prom scraping to the plugins without exposing them directly
The endpoints are
/discovery : HTTP Service Discovery [https://prometheus.io/docs/prometheus/latest/configuration/configuration/#http_sd_config]
Prometheus server is configured to poll this url to discover new endpoints to monitor. The node serves the response based on what plugins are running,
/plugins/<name>/metrics: The node acts as very thin middleware to route from Prometheus server scrape requests to individual plugin /metrics endpoint
Once a plugin is discovered via the discovery mechanism above, the Prometheus service calls the target endpoint at the scrape interval
The node acts as middleware to route the request to the /metrics endpoint of the requested plugin
The simplest change to monitor LOOPPs is to add a service discovery to the scrape configuration
- job_name: 'chainlink_node' ...
- http_sd_configs:
-
- url: "http://127.0.0.1:6688/discovery" -
refresh_interval: 30s
See the Prometheus documentation for full details [https://prometheus.io/docs/prometheus/latest/configuration/configuration/#http_sd_config]
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrExists = errors.New("plugin already registered")
Functions ¶
func NewCmdFactory ¶
func NewCmdFactory(register func(id string) (*RegisteredLoop, error), lcfg CmdConfig) (func() *exec.Cmd, error)
NewCmdFactory is helper to ensure synchronization between the loop registry and os cmd to exec the LOOP
Types ¶
type CmdConfig ¶
type CmdConfig struct {
ID string // unique string used by the node to track the LOOP. typically supplied by the loop logger name
Cmd string // string value of executable to exec
}
CmdConfig is configuration used to register the LOOP and generate an exec
type LoopRegistry ¶
type LoopRegistry struct {
// contains filtered or unexported fields
}
LoopRegistry is responsible for assigning ports to plugins that are to be used for the plugin's prometheus HTTP server, and for passing the tracing configuration to the plugin.
func NewLoopRegistry ¶
func NewLoopRegistry(lggr logger.Logger, tracingConfig config.Tracing) *LoopRegistry
func (*LoopRegistry) Get ¶
func (m *LoopRegistry) Get(id string) (*RegisteredLoop, bool)
Get plugin by id. Safe for concurrent use.
func (*LoopRegistry) List ¶
func (m *LoopRegistry) List() []*RegisteredLoop
Return slice sorted by plugin name. Safe for concurrent use.
func (*LoopRegistry) Register ¶
func (m *LoopRegistry) Register(id string) (*RegisteredLoop, error)
Register creates a port of the plugin. It is not idempotent. Duplicate calls to Register will return ErrExists Safe for concurrent use.
type RegisteredLoop ¶
type RegistrarConfig ¶
type RegistrarConfig interface {
RegisterLOOP(loopId string, cmdName string) (func() *exec.Cmd, loop.GRPCOpts, error)
}
RegistrarConfig generates contains static configuration inher
func NewRegistrarConfig ¶
func NewRegistrarConfig(grpcOpts loop.GRPCOpts, loopRegistrationFn func(loopId string) (*RegisteredLoop, error)) RegistrarConfig
NewRegistrarConfig creates a RegistarConfig loopRegistrationFn must act as a global registry function of LOOPs and must be idempotent. The [func() *exec.Cmd] for a LOOP should be generated by calling [RegistrarConfig.RegisterLOOP]
Source Files
Directories