admin

README

Intro

Admin tool allows us to dynamically change settings of the running node without a restart. It can be used to change log level, and turn on profiler etc.

Usage

List all commands

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "list-commands"}'

To change log level

Flow, and other zerolog-based libraries:

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "set-log-level", "data": "debug"}'

libp2p, badger, and other golog-based libraries:

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "set-golog-level", "data": "debug"}'

To get the latest finalized block

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "read-blocks", "data": { "block": "final" }}'

To get the latest sealed block

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "read-blocks", "data": { "block": "sealed" }}'

To get block by height

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "read-blocks", "data": { "block": 24998900 }}'

To get identity by peer id

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "get-latest-identity", "data": { "peer_id": "QmNqszdfyEZmMCXcnoUdBDWboFvVLF5reyKPuiqFQT77Vw" }}'

To get transactions for ranges (only available to staked access and execution nodes)

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "get-transactions", "data": { "start-height": 340, "end-height": 343 }}'

To get blocks for ranges (works for any node type, for block payload, only prints the collection ids)

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "read-range-blocks", "data": { "start-height": 105172044, "end-height": 105172047 }}'

To get cluster block for ranges (only available to collection nodes, only prints the transaction ids)

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "read-range-cluster-blocks", "data": { "chain-id": "cluster-576-e8af4702d837acb77868a95f61eb212f90b14c6b7d61c89f48949fd27d1a269b", "start-height": 25077, "end-height": 25080 }}'

To get execution data for a block by execution_data_id (only available execution nodes and access nodes with execution sync enabled)

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "read-execution-data", "data": { "execution_data_id": "2fff2b05e7226c58e3c14b3549ab44a354754761c5baa721ea0d1ea26d069dc4" }}'

To get a list of all updatable configs

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "list-configs"}'

To get a config value

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "get-config", "data": "consensus-required-approvals-for-sealing"}'

To set a config value

Example: require 1 approval for consensus sealing

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "set-config", "data": {"consensus-required-approvals-for-sealing": 1}}'

TODO remove

Example: set block rate delay to 750ms

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "set-config", "data": {"hotstuff-block-rate-delay": "750ms"}}'

Example: enable the auto-profiler

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "set-config", "data": {"profiler-enabled": true}}'

Example: manually trigger the auto-profiler for 1 minute

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "set-config", "data": {"profiler-trigger": "1m"}}'

Set a stop height

curl localhost:9002/admin/run_command -H 'Content-Type: application/json' -d '{"commandName": "stop-at-height", "data": { "height": 1111, "crash": false }}'

Documentation

Index

• Constants
• func IsInvalidAdminParameterError(err error) bool
• func NewAdminServer(cr *CommandRunner) *adminServer
• type CommandHandler
• type CommandRequest
• type CommandRunner
  • func (r *CommandRunner) Done() <-chan struct{}
  • func (r *CommandRunner) GrpcAddress() string
  • func (r *CommandRunner) Ready() <-chan struct{}
  • func (r *CommandRunner) Start(ctx irrecoverable.SignalerContext)
• type CommandRunnerBootstrapper
  • func NewCommandRunnerBootstrapper() *CommandRunnerBootstrapper
  • func (r *CommandRunnerBootstrapper) Bootstrap(logger zerolog.Logger, bindAddress string, opts ...CommandRunnerOption) *CommandRunner
  • func (r *CommandRunnerBootstrapper) RegisterHandler(command string, handler CommandHandler) bool
  • func (r *CommandRunnerBootstrapper) RegisterValidator(command string, validator CommandValidator) bool
• type CommandRunnerOption
  • func WithGRPCAddress(address string) CommandRunnerOption
  • func WithMaxMsgSize(size int) CommandRunnerOption
  • func WithTLS(config *tls.Config) CommandRunnerOption
• type CommandValidator
• type InvalidAdminReqError
  • func NewInvalidAdminReqErrorf(msg string, args ...any) InvalidAdminReqError
  • func NewInvalidAdminReqFormatError(msg string, args ...any) InvalidAdminReqError
  • func NewInvalidAdminReqParameterError(field string, msg string, actualVal any) InvalidAdminReqError
  • func (err InvalidAdminReqError) Error() string
  • func (err InvalidAdminReqError) Unwrap() error

Constants

const CommandRunnerShutdownTimeout = 5 * time.Second

Functions

func IsInvalidAdminParameterError

func IsInvalidAdminParameterError(err error) bool

func NewAdminServer

func NewAdminServer(cr *CommandRunner) *adminServer

Types

type CommandHandler

type CommandHandler func(ctx context.Context, request *CommandRequest) (interface{}, error)

type CommandRequest

type CommandRequest struct {
	// Data is the payload of the request, generated by the request initiator.
	// This is populated by the admin command framework and is available to both
	// Validator and Handler functions.
	Data interface{}
	// ValidatorData may be optionally set by the Validator function, and will
	// then be available for use in the Handler function.
	ValidatorData interface{}
}

CommandRequest is the structure of an admin command request.

type CommandRunner

type CommandRunner struct {
	// contains filtered or unexported fields
}

func (*CommandRunner) Done

func (r *CommandRunner) Done() <-chan struct{}

func (*CommandRunner) GrpcAddress

func (r *CommandRunner) GrpcAddress() string

func (*CommandRunner) Ready

func (r *CommandRunner) Ready() <-chan struct{}

func (*CommandRunner) Start

func (r *CommandRunner) Start(ctx irrecoverable.SignalerContext)

type CommandRunnerBootstrapper

type CommandRunnerBootstrapper struct {
	// contains filtered or unexported fields
}

func NewCommandRunnerBootstrapper

func NewCommandRunnerBootstrapper() *CommandRunnerBootstrapper

func (*CommandRunnerBootstrapper) Bootstrap

func (r *CommandRunnerBootstrapper) Bootstrap(logger zerolog.Logger, bindAddress string, opts ...CommandRunnerOption) *CommandRunner

func (*CommandRunnerBootstrapper) RegisterHandler

func (r *CommandRunnerBootstrapper) RegisterHandler(command string, handler CommandHandler) bool

func (*CommandRunnerBootstrapper) RegisterValidator

func (r *CommandRunnerBootstrapper) RegisterValidator(command string, validator CommandValidator) bool

type CommandRunnerOption

type CommandRunnerOption func(*CommandRunner)

func WithGRPCAddress

func WithGRPCAddress(address string) CommandRunnerOption

func WithMaxMsgSize

func WithMaxMsgSize(size int) CommandRunnerOption

func WithTLS

func WithTLS(config *tls.Config) CommandRunnerOption

type CommandValidator

type CommandValidator func(request *CommandRequest) error

type InvalidAdminReqError

type InvalidAdminReqError struct {
	Err error
}

InvalidAdminReqError indicates that an admin request has failed validation, and the request will not be processed. All Validator functions must return this error if the request was invalid.

func NewInvalidAdminReqErrorf

func NewInvalidAdminReqErrorf(msg string, args ...any) InvalidAdminReqError

func NewInvalidAdminReqFormatError

func NewInvalidAdminReqFormatError(msg string, args ...any) InvalidAdminReqError

NewInvalidAdminReqFormatError returns an InvalidAdminReqError indicating that the request data format is invalid.

func NewInvalidAdminReqParameterError

func NewInvalidAdminReqParameterError(field string, msg string, actualVal any) InvalidAdminReqError

NewInvalidAdminReqParameterError returns an InvalidAdminReqError indicating that a field of the request has an invalid value.

func (InvalidAdminReqError) Error

func (err InvalidAdminReqError) Error() string

func (InvalidAdminReqError) Unwrap

func (err InvalidAdminReqError) Unwrap() error