fetch

package
v0.0.0-...-63eda7f Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: Apache-2.0 Imports: 104 Imported by: 0

Documentation

Overview

Package fetch gets a collector's raw data. It holds the request types (http and localfile, each in its own build-tagged file), their validation and the probe parameters they accept, path parameters and request templates, and the cached HTTP transports.

Index

Constants

View Source
const (
	// DefaultLocalFileMaxFiles is request.max_files when unset.
	DefaultLocalFileMaxFiles = 100
	// DefaultLocalFileMaxTotalBytes is request.max_total_bytes when unset.
	DefaultLocalFileMaxTotalBytes = 64 << 20
)
View Source
const (
	RequestTypeHTTP       = "http"
	RequestTypeLocalFile  = "localfile"
	RequestTypeGraphite   = "graphite"
	RequestTypeGRPC       = "grpc"
	RequestTypeSSHFile    = "sshfile"
	RequestTypeSQL        = "sql"
	RequestTypeDNS        = "dns"
	RequestTypeTLSCert    = "tlscert"
	RequestTypeS3File     = "s3file"
	RequestTypeKubernetes = "kubernetes"
	RequestTypeRedis      = "redis"
	RequestTypeTCP        = "tcp"
	RequestTypeLDAP       = "ldap"
	RequestTypeSSHExec    = "sshexec"
	RequestTypeNTP        = "ntp"
	RequestTypeICMP       = "icmp"
	RequestTypeSNMP       = "snmp"
)

The request types in the source tree.

View Source
const (
	SQLDriverMySQL      = "mysql"
	SQLDriverPostgres   = "postgres"
	SQLDriverSQLServer  = "sqlserver"
	SQLDriverOracle     = "oracle"
	SQLDriverClickHouse = "clickhouse"
	SQLDriverSnowflake  = "snowflake"
	SQLDriverVertica    = "vertica"
)

The database drivers of the sql request type, by the names request.driver gives them (sqldriver.go). They are named in every build, so that the schema and the collectors page can name them whatever the build carries.

View Source
const AcceptAnyStatus = "any"

AcceptAnyStatus is the entry of request.accept_status that accepts every status from 100 to 599, for a collector that reports whatever the target answered, such as an uptime check, without listing the five classes. It says all there is to say, so it is written alone; retry.statuses, which lists what is not accepted, does not take it.

View Source
const DefaultKubernetesMaxObjects = 10000

DefaultKubernetesMaxObjects is how many objects a listing may hold when request.max_objects is left out; one more fails the scrape.

View Source
const DefaultLDAPMaxEntries = 1000

DefaultLDAPMaxEntries is how many entries a search that is not count_only may match when its max_entries is left out; one more fails the scrape.

View Source
const FastCGIParamPattern = `^[A-Za-z_][A-Za-z0-9_]*$`

FastCGIParamPattern is fastcgiParamName, for the schema.

View Source
const GraphiteContentType = "text/x-graphite"

GraphiteContentType is the Content-Type a local file of carbon plaintext lines is given by its extension, .graphite or .carbon, so decoder.type auto reads it with the graphite decoder.

View Source
const MaxRetryAttempts = 10

MaxRetryAttempts is the most retries one trip may make, however the collector, a static target or a probe parameter asks: whoever can reach /probe chooses retry_attempts and retry_backoff, and without a bound one probe of a failing target could send it requests in a tight loop until its deadline.

View Source
const OutsideASCIIPattern = `[^\x00-\x7F]`

OutsideASCIIPattern matches what no entry of request.allowed_targets or request.denied_targets holds, a character outside ASCII, for the configuration's JSON Schema: an entry is written in ASCII, as a host is (canonicalHost). What else an entry has to be is the exporter's to refuse.

View Source
const PathParamPrefix = "param_"

PathParamPrefix is shared by placeholders and the probe parameters that fill them. A probe parameter without it can never be a path parameter, so the two namespaces cannot collide with target, collector, path, method and the rest.

View Source
const ProxyURLPattern = `^$|^direct$|^([Hh][Tt][Tt][Pp][Ss]?|[Ss][Oo][Cc][Kk][Ss]5[Hh]?)://[^/?#@{}]+/?$`

ProxyURLPattern is what request.proxy_url may be, for the configuration's JSON Schema: left out, direct, or a proxy's scheme, host and port, with no credentials and nothing after the port. The scheme is of any case, as the exporter reads it (url.Parse lowers it); it is spelled in classes rather than with (?i), which JSON Schema's ECMA-262 patterns do not have. What else it has to be is the exporter's to refuse.

View Source
const Redacted = "<redacted>"

Redacted stands in for what is withheld.

View Source
const SchemaSurroundingBlank = `\t\n\v\f\r \x85\xA0` + "  - 

   "

SchemaSurroundingBlank is a regular expression class of the characters strings.TrimSpace takes off a text, written so that Go and JavaScript read it alike: the two below U+0100 that are no ASCII as escapes, the rest as themselves.

View Source
const TrustedHostPattern = `` /* 256-byte string literal not displayed */

TrustedHostPattern is what an entry of request.redirect_trusted_hosts looks like, for the configuration's JSON Schema: "*" alone; a host name or a glob of one, with a final dot or without, which is digits and dots only or holds a letter, a hyphen or an underscore; or something written as an IPv6 address is, with two colons at least. It refuses what parseTrustedHost refuses but an address of that shape that is none, which a pattern cannot tell.

View Source
const UnforwardablePrefix = "Proxy-"

UnforwardablePrefix starts the name of every header that is never forwarded besides the ones listed (UnforwardableHeaderNames).

View Source
const UnixSocketPattern = `^$|^/`

UnixSocketPattern is what request.unix_socket may be, an http or tcp collector's (unixsocketpath.go), for the configuration's JSON Schema: an absolute path, or "", which is the key left out. What else it has to be is the exporter's to refuse.

Variables

View Source
var DefaultRetryStatuses = []string{"408", "425", "429", "5xx"}

DefaultRetryStatuses are the statuses an http or graphite request retries when retry.statuses is left out: those that say the target could not answer now, and may on the next attempt — 408 Request Timeout, 425 Too Early, 429 Too Many Requests and every 5xx.

View Source
var ErrMissingTarget = errors.New("target is required")

ErrMissingTarget is CheckTarget's answer to a target left out by a type that needs one; each caller words it for its own audience.

View Source
var ErrTargetRefused = errors.New("target refused")

ErrTargetRefused matches every TargetRefusedError with errors.Is.

View Source
var IPFamilies = []string{"ip4", "ip6", "prefer_ip4", "prefer_ip6"}

IPFamilies are the values request.ip_family may take.

View Source
var PathParamName = regexp.MustCompile(`^param_[A-Za-z0-9_]+$`)

PathParamName matches the name of a path parameter, PathParamPrefix followed by letters, digits and underscores.

View Source
var RequestTypes = map[string]*RequestType{}

RequestTypes is the registry of the types built into this binary. Each type registers itself from its own requesttype_<name>.go file, whose build constraint decides whether the type is included:

//go:build !select_request_types || request_type_<name>

A default build carries every type but the opt-in ones (optInRequestTypes), none now, whose files would be built under their own tag alone:

//go:build request_type_<name>

so that -tags request_type_<name> is a default build with that type added. Building with -tags select_request_types,request_type_http carries only the listed ones; the others, and everything only they import, are left out of the binary.

The map is a variable, rather than being built once, only so a test can register a fixture type to exercise the per-type rules with more than one type.

Functions

func AcceptedStatus

func AcceptedStatus(c *model.Collector, overrides RequestOverrides, status int) bool

AcceptedStatus says whether a response with status is decoded: one of request.accept_status, a static target's replacing the collector's, or any 2xx when there is none.

func AnswerHintOf

func AnswerHintOf(c *model.Collector) string

AnswerHintOf says what a response of c pasted on the debug page is (RequestType.AnswerHint); "" for a type this build lacks.

func AnswersHTTP

func AnswersHTTP(c *model.Collector) bool

AnswersHTTP reports whether the answers of c are HTTP responses, with a status and headers of their own: those of a type whose stage is http's (FetchStage), http's and graphite's. Another type's answer, a file, rows or a document the exporter makes, has neither.

func BuiltRequestTypes

func BuiltRequestTypes() []string

BuiltRequestTypes lists the types this binary was built with, sorted.

func BuiltSQLDrivers

func BuiltSQLDrivers() []string

BuiltSQLDrivers lists the database drivers this binary's sql request type can use, sorted: what --version, the startup log and http_exporter_build_info report. Empty when the build has no sql type.

func CanonicalDNSName

func CanonicalDNSName(raw string) (string, error)

CanonicalDNSName reads a DNS name as canonicalHost reads a host, held besides to the lengths of the DNS: at most 253 characters, each label from 1 to 63. It returns the name in lower case without a trailing dot; a name canonicalHost refuses is refused with its *TargetRefusedError, and one of the wrong length with an error starting with the name quoted.

func CheckBasicUsername

func CheckBasicUsername(username string) error

CheckBasicUsername refuses the username of a Basic credential that holds a colon. The credential is the username and the password joined by a colon (RFC 7617), and a server splits it at the first one: a username with one in it reaches the server as a shorter username and a password that starts with the rest of it, and is refused there on every scrape, or is never matched by the exporter's own web.basic_auth. The value itself is never shown.

func CheckClientTLS

func CheckClientTLS(t model.TLSConfig) error

CheckClientTLS refuses a tls block that names a client certificate without its key, or a key without its certificate, as a collector's request.tls is refused, and one whose files cannot be read or hold no certificate or key: unlike a collector's, which are read at the first request to a target, these are needed from the start, by a request the exporter makes on its own.

func CheckClientTLSKeys

func CheckClientTLSKeys(t model.TLSConfig) error

CheckClientTLSKeys is CheckClientTLS without reading the files: it refuses only a client certificate without its key, or a key without its certificate. The target allocator checks a configuration with it, since the files are mounted on the replicas and not on the allocator.

func CheckHTTPMethod

func CheckHTTPMethod(written string) (string, error)

CheckHTTPMethod is a method written as HTTPMethodSpellings has it, in upper case, as it is sent, or an error naming the spellings taken.

func CheckHeaderValue

func CheckHeaderValue(value string) error

CheckHeaderValue refuses a header value with a control character other than tab, which Go refuses to send: the check a collector's request.headers values are held to, for a value that only arrives with a probe.

func CheckHeaders

func CheckHeaders(headers map[string]string) error

CheckHeaders applies the checks of a collector's request.headers to headers that take no placeholders: every name is one Go sends, none is set twice in different case, and no value holds a control character.

func CheckOverrideParams

func CheckOverrideParams(c *model.Collector, values url.Values) error

CheckOverrideParams rejects probe parameters that belong to a different request type than the collector's.

func CheckPathParams

func CheckPathParams(c *model.Collector, overrides RequestOverrides) error

CheckPathParams validates a probe's path parameters against the collector before anything is fetched, so a missing value is the caller's 400 rather than a failed scrape of the target.

A parameter the path does not use is rejected too. It is almost always a misspelling — param_tenat for param_tenant — and when the placeholder has a default, the misspelled scrape would otherwise succeed against the default tenant and report its numbers as the intended one's. A parameter that fills a label value of the collector is used (labelparams.go).

The refusal names the places a placeholder of the collector can stand in, which are those of its request type (requestTemplates): an operator sent to look at the body of a graphite collector, which has none, or past the expressions that hold its placeholders, looks in the wrong place.

func CheckProxy

func CheckProxy(proxyURL string, files *model.ProxyBasicAuthFile) error

CheckProxy refuses a request.proxy_url that names no proxy a request can be sent through, and a request.proxy_basic_auth_file without both its paths, whether a collector or a defaults block writes them; "" and model.ProxyDirect, and no files, pass.

func CheckRequestParams

func CheckRequestParams(c *model.Collector, overrides RequestOverrides) (unused []string, err error)

CheckRequestParams binds every placeholder of a request against the parameters without sending anything, so a missing or unfit value is known before the target is contacted, and reports parameters nothing uses. The placeholders of the collector's label values are bound with them (labelparams.go): a parameter one of those names is used, whatever the request names and whatever of it the probe replaced.

func CheckTarget

func CheckTarget(c *model.Collector, target string, static bool) error

CheckTarget validates a probe's or a static target's target for the collector's type.

func CheckTargetRequest

func CheckTargetRequest(t *model.StaticTarget, c *model.Collector) error

CheckTargetRequest rejects a static target request block that sets keys its collector's request type does not accept. It writes nothing into the target, which may be in force and read by a scrape (NormalizeTargetRequest).

func CloseConnections

func CloseConnections()

CloseConnections closes every connection a built type keeps across scrapes, for the exporter's shutdown, and forgets the rate limits' buckets and counts with them.

func CollectorConnectionLimit

func CollectorConnectionLimit(requestType, collector string) (waited, failed uint64)

CollectorConnectionLimit reports how many scrapes of a collector of requestType waited for room at its limit on connections, and how many failed there (RequestType.ConnectionLimit); zero for a type without one.

func CollectorConnections

func CollectorConnections(requestType, collector string) (open int, made uint64)

CollectorConnections reports the connections a collector of requestType has open now and how many it has made (RequestType.Connections); zero for a type that keeps none.

func CollectorLabelDefaults

func CollectorLabelDefaults(c *model.Collector, name, text string) (least string, templated bool)

CollectorLabelDefaults is the transform.labels value of name, written as text, measured so, and whether it is one of the collector's values that hold a placeholder: text itself, and false, when it is not.

func CollectorLogins

func CollectorLogins(requestType, collector string) (made, failed uint64)

CollectorLogins reports how many logins a collector of requestType made and how many failed (RequestType.Logins); zero for a type that does not log in.

func CollectorRateLimit

func CollectorRateLimit(collector string) (waited, refused uint64)

CollectorRateLimit reports how many requests of a collector waited for their turn under its request.rate_limit, or a static target's, and how many it refused for a wait past their deadline.

func ConfiguredMethod

func ConfiguredMethod(c *model.Collector) string

ConfiguredMethod is the method of a collector's request as its configuration writes it, its default filled in once validated, which a static target or a probe may replace; "" for a type whose request has none of its own (RequestType.MethodBody).

func ConfiguredQuery

func ConfiguredQuery(c *model.Collector) func(name, value string) bool

ConfiguredQuery says, of a query pair of a request c made, its name and its value as a server reads them, whether c's configuration set it as it was sent: a value of request.query without placeholders, and what its type sets itself (RequestType.ShownQuery). It says nothing of the name's reading as a credential's, which RedactRequestURL masks whatever this says. A static target's own request keys are not the collector's, and are not shown.

func CredentialName

func CredentialName(name string) bool

CredentialName reports whether a name — a header's, a query parameter's, or a field's in text — reads as a credential's, in any case: Authorization, Cookie, X-Api-Key, X-Auth-Token, apikey, sig, db_pwd, userPass and the like. The name is read word by word (nameParts): it reads as a credential's when one of credentialParts is a word of it, whole, or when a credential word is anywhere in it once its ordinary words (ordinaryWords) are taken out. A credential word is looked for across a change to upper case too, since toKen is still token to a reader, but not across punctuation or an ordinary word. A name not split into words where it should be errs towards masking: authortoken holds token.

func DNSResolver

func DNSResolver(server string, tcp bool) *net.Resolver

DNSResolver is Go's own resolver (PreferGo), which needs no library and tells a name that does not exist, or has no records of the type, from a failure. With server, host:port as ParseDNSServer writes it, every question goes there instead of to the system's nameservers; with tcp, over TCP. Over UDP an answer marked truncated is asked again over TCP, as the resolver always does.

func DefaultKeyApplies

func DefaultKeyApplies(c *model.Collector, key string) bool

DefaultKeyApplies says whether a request key of a defaults block, by its top name, applies to c, whose request type takes it (RequestType.DefaultApplies).

func DisplayTarget

func DisplayTarget(c *model.Collector, target string) string

DisplayTarget renders a target for logs and labels, by the collector's type.

func FetchErrorStage

func FetchErrorStage(c *model.Collector, err error) string

FetchErrorStage names the stage a failed fetch is reported under: the stage a StageError names, else the type's fetch stage.

func FetchStage

func FetchStage(c *model.Collector) string

FetchStage names the stage a failed fetch is reported under.

func FileIdentity

func FileIdentity(st os.FileInfo) (dev, ino uint64, ok bool)

FileIdentity tells which file st, the stat of a path following its links, is: its device and inode, which another file never has while this one exists, where the system puts them in the stat (fileidentity_unix.go), and ok false where it does not. It looks at nothing beyond the stat, so the check of a grpc collector's descriptor files at each call and the configuration's watch, which both stamp a file with it, tell the same change of file at no cost beyond the stat they make anyway: a file renamed over by another of the same time, size and permissions is another file to both.

The device and inode are what the filesystem reports. One that does not keep a file's inode number while the file stays as it is — a FUSE filesystem mounted without use_ino, once the kernel has dropped the file from its cache, or the same files mounted again — gives the file another identity, and both take it for another file: the next call compiles the files again and the next tick of the watch reloads, once for each time the number changes.

func FileWarnings

func FileWarnings(c *model.Collector, t *model.StaticTarget) []string

FileWarnings reads the files the request of c names, or of the static target t when it is set, as a request would, and says what a request would find wrong with them (RequestType.CheckFiles); none for a type that reads no file at a request.

func FilledLabels

func FilledLabels(c *model.Collector, params map[string]string) (*model.Collector, error)

FilledLabels returns c as a transform reads it for a probe with params: c itself when its label values hold no placeholder, and otherwise a copy whose transform.labels and metric rules' labels have their placeholders filled in, so that everything reading a label value finds what it would find had the filled text been written in the configuration. c, which the probes of a collector share, is not written to: the copy has its own transform.labels, and its own rules where one of them has a filled label.

A value filled to nothing is the label left out, as a label with an empty value is everywhere: a transform.labels value of "" sets nothing, so a series keeps a label of that name it has of its own, and a rule's label is taken out of the copy's rule, which then gives its series no such label.

The probe's parameters were checked before the target was contacted (CheckPathParams), and a static target's when its file loaded, so an error here is of a caller that checked neither.

func FollowConfiguration

func FollowConfiguration(collectors []model.Collector, targets []model.StaticTarget)

FollowConfiguration tells every built type that keeps connections across scrapes which collectors and static targets are in force now (RequestType.Follow).

func FollowHostRateLimits

func FollowHostRateLimits(entries []model.HostRateLimit)

FollowHostRateLimits puts the entries of rate_limits of the configuration in force in force for the requests. The bucket of an entry a reload left as it was is kept, with the turns it has promised; that of an entry it changed, in its hosts or its limit, is dropped, the entry starting from a full bucket, as a collector's changed request.rate_limit does. The counts of an entry are kept while an entry of its name is in force.

func GRPCStatusCode

func GRPCStatusCode(c *model.Collector, err error) (code int, ok bool)

GRPCStatusCode is the gRPC status code a fetch of a grpc collector ended with: 0 when err is nil, the code of a call that failed, and -1 when no call was made, as when the message did not encode. ok reports whether the collector is a grpc one at all: of a type whose answers carry gRPC status codes (RequestType.StatusCodes).

func GoTypeShape

func GoTypeShape(t reflect.Type) (string, error)

GoTypeShape is the shape of t as the catalogue holds it, as JSON, or why the catalogue cannot hold it.

func HTTPClient

func HTTPClient(settings TransportSettings, followRedirects bool, timeout time.Duration) (*http.Client, error)

HTTPClient is a client on the cached transport for settings. The client itself is cheap and carries the per-request redirect policy and timeout.

func HTTPMethodSpellings

func HTTPMethodSpellings() []string

HTTPMethodSpellings are the ways request.method may be written, a collector's and a static target's: each of httpMethods in upper case, as HTTP names them, or in lower case. The schemas take these alone, and so does the exporter, rather than any case, which no schema enum can list.

func HasPathParams

func HasPathParams(path string) bool

HasPathParams is the cheap test every caller makes first, so a path with no placeholders takes exactly the code path it always did.

func HasValidator

func HasValidator(h http.Header) bool

HasValidator reports whether the response can be revalidated.

func IdempotentMethod

func IdempotentMethod(method string) bool

IdempotentMethod reports whether sending a request with method twice has the effect of sending it once, so a failed one may be retried without asking: GET, HEAD, OPTIONS, TRACE, PUT and DELETE (RFC 9110). An empty method is GET.

func LoginFingerprint

func LoginFingerprint(l *model.LoginConfig) string

LoginFingerprint identifies a static target's login, for its key in the response cache: targets that log in differently share no answer.

func LoginHeader

func LoginHeader(l *model.LoginConfig) string

LoginHeader is the header a login's token is sent in: login.header, Cookie with token_cookie, Authorization otherwise.

func LoginPrefix

func LoginPrefix(l *model.LoginConfig) string

LoginPrefix is what the token is sent after: login.prefix, the cookie's name and = with token_cookie, "Bearer " in Authorization, and nothing in any other header.

func NamedFiles

func NamedFiles(c *model.Collector) []string

NamedFiles returns the files a collector's request names that checking it reads when the configuration loads (RequestType.NamedFiles): for a grpc collector, its request.protoset_file and request.proto_files, which its method and message are checked against. The collector need not have been validated, its request.type being taken as ReadFiles takes it.

func NormalizeTargetRequest

func NormalizeTargetRequest(t *model.StaticTarget)

NormalizeTargetRequest writes a static target's request.accept_status, request.retry.statuses, request.accept_codes and request.retry.codes as a scrape compares them: a class in lower case (canonicalStatus), and codes trimmed and in upper case. It is called once, when the target file is loaded; whether each entry is one the collector's request type takes is CheckTargetRequest's to say.

func ParseDNSServer

func ParseDNSServer(raw string) (string, error)

ParseDNSServer reads a DNS server: host, host:port or [v6]:port, port 53 when it names none. Nothing else may come with it. It returns the server as host:port, the host as canonicalHost writes it.

func ParseLabelParams

func ParseLabelParams(c *model.Collector, ruleName func(index int) string) (*model.LabelParams, error)

ParseLabelParams reads the placeholders of c's label values: those of transform.labels, and those of its metric rules' static labels, each rule named by ruleName as the collector's other errors name it. It returns nil when no value holds one. A placeholder that is not well formed — unclosed, written with a space after the braces, named otherwise than param_<name>, with a filter or a brace in its default — and a default that is not valid UTF-8 are refused, naming the collector and the value.

A label that has an expression is not static, whatever its value says beside it, and is not read: the check of a rule refuses it.

func RateLimitBurst

func RateLimitBurst(l *model.RateLimitConfig) int

RateLimitBurst is the burst of l in force: its own, or 1.

func ReadCredentialFile

func ReadCredentialFile(path string) (string, error)

ReadCredentialFile reads a credential from the file at path, without the surrounding whitespace an editor or a Secret mount may leave.

func ReadFiles

func ReadFiles(c *model.Collector) (paths []string, read string)

ReadFiles returns the paths that checking a collector's request looked at on disk when the files the request names lead to others: for a grpc collector with descriptors: proto, its .proto files, the files those import, and the places an imported file was looked for at and not found. The watch of the configuration stamps them while a reload is refused, so a reload refused for an imported file is tried again when that file changes or appears, as one refused for a file the configuration names is, and while the configuration is in force, so one changing is checked against the configuration at the next tick.

The files are read now when they were never read, or changed since they were. read is a mark of the reading the paths are of: the same mark from a later call says nothing the reading looked at has changed between the reading and that call.

The collector need not have been validated: the watch asks before the configuration is, to stamp the files before the validation reads them. Its request.type is taken as written, as ValidateRequest takes it, so a collector written `type: GRPC`, which the validation refuses, has none.

func RedactHeaderValue

func RedactHeaderValue(name, value string) string

RedactHeaderValue is a header's value as it may be shown: Redacted when the name reads as a credential's, and otherwise, for a header that carries a URL, the value with its URL masked as a debug report's request line masks one (RedactRequestURL): Location and Content-Location, which are a URL whole, Refresh's url=, and each <…> of Link. A redirect's Location is where the request goes next, and carries what it does: a session in its path, an OAuth code or a token in its query.

func RedactRequestURL

func RedactRequestURL(raw string, configured func(name, value string) bool) string

RedactRequestURL is a request's URL as a debug report's request line shows it: as RedactURLString with MaskQueryValues shows it, but for the values of the query pairs configured says the request's configuration set (ConfiguredQuery), which are shown as they were sent. A pair a probe parameter, a placeholder or the target gave keeps its value masked, and so does one whose name reads as a credential's; the userinfo is withheld and the fragment dropped as ever.

func RedactShownURLQuery

func RedactShownURLQuery(shown string, configured func(name, value string) bool) string

RedactShownURLQuery is a URL as $url has it (HTTPTrip.ShownURL), its path's parameters and its query's credentials already masked, with the values of its query masked as a debug report's request line masks them (RedactRequestURL), configured saying which pairs are shown. The URL is not parsed again: a path with <redacted> in it, which a path would have escaped, would no longer keep its own escapes, and Go would write it again in its own, /a;%6Asessionid as /a;jsessionid, so the report's $url would differ from the one the rules read. Only what follows the first ? is masked, the path holding none of its own unescaped.

func RedactText

func RedactText(text string) string

RedactText masks what reads as a credential in text the exporter did not write, such as an error page's body it logs the start of: a bearer or basic credential, a JSON Web Token, a URL's userinfo, and the value of a key, a field or an XML element whose name reads as a credential's (CredentialName, the rule a header's and a query parameter's name are held to), and of a URL's query or path parameter whose name reads as a query parameter's would (textCredential). It errs towards masking: a word that only looks like a credential's value may be masked too.

func RedactURL

func RedactURL(u *url.URL, how URLRedaction) string

RedactURL renders u with its credentials withheld as how says. u itself is left alone. Whatever how says, the value of a path parameter whose name reads as a credential's is masked (maskPathParams).

func RedactURLErrors

func RedactURLErrors(err error) error

RedactURLErrors withholds the credentials of every URL quoted by a *url.Error in err's chain — Go's HTTP client quotes the whole URL it requested, query and all, in the error of a request that failed, and url.Parse quotes the text it could not parse — as a debug report shows a URL (MaskQueryValues). The errors that wrap one have already written its URL into their text, so the text is rewritten as a whole: the result reads with each URL redacted, and unwraps to err, so errors.Is and errors.As still see what they did. A nil err, or one quoting no URL, is returned as it is.

func RedactURLString

func RedactURLString(raw string, how URLRedaction) string

RedactURLString is RedactURL for a URL not yet parsed: one that does not parse is withheld whole, since its credentials cannot be found to redact.

func RequestLabelFor

func RequestLabelFor(target string, c *model.Collector, overrides RequestOverrides) (string, error)

RequestLabelFor is the url label of a request, by the collector's type.

func RequestMethodFor

func RequestMethodFor(c *model.Collector, overrides RequestOverrides) string

RequestMethodFor is the http_method label of a request, by the collector's type.

func ResponseLimit

func ResponseLimit(c *model.Collector) int64

ResponseLimit is responseLimit, for a response that was not fetched: the debug page holds a pasted body to the limit a fetched one would be held to (exporter/debugpage.go).

func RetriesOf

func RetriesOf(c *model.Collector, overrides RequestOverrides) string

RetriesOf says how a request of c, with overrides, made over HTTP is retried, for the debug report: at most how often, how far apart and on what. It is "" when no retry is made — attempts is 0, or an http request's method is not idempotent and retry.non_idempotent is unset — and for a type that is not retried by HTTP status: one without request.retry, and grpc, which retries by code.

func RetryStatuses

func RetryStatuses(c *model.Collector, overrides RequestOverrides) []string

RetryStatuses are the statuses a request of c retries: a static target's retry.statuses, else the collector's, else DefaultRetryStatuses. An empty list is no status at all, not the default.

func Revalidable

func Revalidable(c *model.Collector, overrides RequestOverrides) bool

Revalidable reports whether a request of c, with overrides, is one whose response can be revalidated: a request of a type that says so (RequestType.Revalidates), http and graphite, that fetches one response with GET or HEAD. A paginated collector's response is many responses merged, of which no one validator speaks. Another method is left alone: a matching If-None-Match on it asks for 412 Precondition Failed, not 304 (RFC 9110 § 13.1.2), and a graphite request too long for a URL is sent as a POST (requesttype_graphite.go).

func RuleLabelDefaults

func RuleLabelDefaults(c *model.Collector, rule, label int, text string) (least string, templated bool)

RuleLabelDefaults is CollectorLabelDefaults for the value of the label at index label of the metric rule at index rule.

func SQLNamedResults

func SQLNamedResults(c *model.Collector) bool

SQLNamedResults reports whether a sql collector runs several statements (request.statements), whose document is an object of each one's rows by its name, which only jq, yq and python read, not the list of rows a csv transform reads by column. False in a build without the sql type.

func SchemaCaseless

func SchemaCaseless(text string) string

SchemaCaseless is a regular expression of text matched without regard to case, written so that Go and JavaScript read it alike: each letter as a class of its two cases, anything else escaped as regexp.QuoteMeta escapes it.

func SchemaCaselessOneOf

func SchemaCaselessOneOf(names ...string) string

SchemaCaselessOneOf is the pattern of a text naming one of names as the exporter matches a name such as request.driver or request.record_type: in any case, with blanks around it or not. The spec has a driver and a DNS record type matched so, as their databases and RFCs name them in any case, so the schema takes what the exporter takes rather than the exporter refusing what an enum would.

func SchemaLeastDuration

func SchemaLeastDuration(least time.Duration, zero bool) map[string]any

SchemaLeastDuration is what a duration key whose value is at least least, such as limits.script_timeout's 1ms, refuses, to go under not; zero says whether the key takes zero, as the default or as nothing. Text of one part under the least is refused, but, where zero is taken, a part that comes to no whole nanosecond, which is the zero the exporter reads it as. Where zero is refused, as by failure_backoff.initial, the number 0 and a zero written as text in any way, -0s and 0s0m too, are refused with it.

func SchemaLeastSize

func SchemaLeastSize(least int64) map[string]any

SchemaLeastSize is what a size key whose value, when it is not zero, is at least least bytes, such as limits.max_script_memory's 32MiB, refuses, to go under not: text of a number, with a unit or without, that comes to at least a byte and under the least. A size that comes to no whole byte, 0.5B, is the zero, and the default, it is to the exporter. A size written as a number is held to the least by the key's minimum.

func SchemaOnlyBlanks

func SchemaOnlyBlanks() map[string]any

SchemaOnlyBlanks is text of one blank or more and nothing else: what a key that names something may not be. It goes under not, so that the key keeps the types it takes, and "" stays the key left out.

func SchemaOptionalEnum

func SchemaOptionalEnum(values []string) []string

SchemaOptionalEnum is values with "", which is the key left out, beside them: the allowed values of a key that may be left out.

func SchemaOptionalPattern

func SchemaOptionalPattern(pattern string) string

SchemaOptionalPattern is pattern taking "" too, which is the key left out.

func SchemaWrittenKey

func SchemaWrittenKey(key string) map[string]any

SchemaWrittenKey is the rule that an object has the key and that it is not "": what required alone cannot say, which goes by the key being there, whatever its value. Every rule about a key that may be written "" — one that requires it, or that forbids it beside another — is made of it, so that key: "" is the key left out to the rule as it is to the exporter.

func SetGRPCConnectTimeout

func SetGRPCConnectTimeout(limit time.Duration)

SetGRPCConnectTimeout is how long an attempt to connect to a grpc target may take, on the connections made from now on, which is twenty seconds in the exporter: until the server has answered the HTTP/2 preface, after the TCP connection and the TLS handshake. It is for tests. A connection of a few milliseconds takes far longer on a machine with every CPU busy elsewhere, and a test that is not about the limit then fails by it; such a test runs with a limit of half a minute, the bound of a hang. A test of the limit itself sets a short one, and connects to something that never answers the preface. A connection made before keeps the limit it was made with.

func SetTLSHandshakeTimeout

func SetTLSHandshakeTimeout(limit time.Duration)

SetTLSHandshakeTimeout is how long the TLS handshake of a connection may take in the pools built from now on, which is ten seconds in the exporter. It is for tests. A handshake of a few milliseconds takes far longer on a machine with every CPU busy elsewhere, and a test that is not about the limit then fails by it; such a test runs with a limit of half a minute, the bound of a hang. A test of the limit itself sets a short one, and connects to something that never answers the handshake. A pool built before keeps the limit it was built with.

func TargetHeaders

func TargetHeaders(t *model.StaticTarget) (http.Header, error)

TargetHeaders builds the headers sent to the target. Static targets are operator configuration rather than caller input, so they are applied directly instead of through the collector's forwarding allowlist. Credentials are resolved here so that they are part of the cache key and can never be shared with a request that did not present them.

func TemplatedFields

func TemplatedFields(c *model.Collector) []string

TemplatedFields names the fields of a collector whose {{param_...}} placeholders a probe's parameters fill, as their own errors name them: request.path, what requestTemplates renders, such as request.body and request.headers.<name>, and the values of transform.labels that hold a placeholder, such as transform.labels.tenant (labelparams.go). It is how the configuration knows that a placeholder anywhere else would be used as written, without a second list of where placeholders work to keep in step with this one. The labels of the metric rules, which have no path of their own in a collector, are asked for one by one (TemplatedRuleLabel).

func TemplatedRuleLabel

func TemplatedRuleLabel(c *model.Collector, rule, label int) bool

TemplatedRuleLabel says whether the value of the label at index label of the metric rule at index rule is one whose placeholders a probe's parameters fill: one the collector's parsed label values hold.

func TypeArticle

func TypeArticle(name string) string

TypeArticle is the article the name of the request type is read with in messages (RequestType.Article).

func UnbuiltRequestTypes

func UnbuiltRequestTypes() []string

UnbuiltRequestTypes are the request types of the source tree this binary was built without.

func UnforwardableHeaderNames

func UnforwardableHeaderNames() []string

UnforwardableHeaderNames are the names of the headers a probe never forwards but for those starting with UnforwardablePrefix, canonical and sorted, for the schemas to refuse in request.forward_headers as the configuration does.

func UnforwardableReason

func UnforwardableReason(name string) string

UnforwardableReason says why the header name, canonical, is never forwarded from a probe, or "" when it may be: the probe's forwarding (the exporter's forwardableHeaders) and the check of request.forward_headers at load (checkForwardHeaders) ask it alike.

func UseSQLTestDriver

func UseSQLTestDriver(connect func(ctx context.Context, info SQLConnectInfo) (driver.Conn, error)) (restore func())

UseSQLTestDriver makes every connection of the sql request type with connect, in place of the drivers, until the function it returns is called: for the tests of other packages, which reach a stand-in database through the very pools and connectors a real driver is reached through.

func ValidateHostRateLimits

func ValidateHostRateLimits(entries []model.HostRateLimit) error

ValidateHostRateLimits checks rate_limits and fills in each entry's burst. An entry needs a name, a label value of its self-metrics and so unique, at least one host, each listed in one entry only and not covered by a wildcard of an earlier entry, and a rate_limit as request.rate_limit's is checked. Every mistake is reported.

The first entry that matches applies, so a host an earlier entry's wildcard matches — an exact name under it, or a narrower wildcard — could never apply where it is listed: it is refused as the same host listed twice is, and the error says to list the narrower first, the way to carve a host out of a wildcard. Within one entry a host its own wildcard covers is harmless, the entry applying to it either way, and is let be.

func ValidateRequest

func ValidateRequest(c *model.Collector) error

ValidateRequest checks a collector's request block: the type is present and known, every key set belongs to that type, and the type's own rules hold. The keys are checked before the type validates, so a default the type fills in, such as method GET, is never mistaken for something the author wrote.

The type is taken as written, in lower case and without blanks around it, the one spelling the schemas take; one written otherwise is refused, saying how the type it names is written.

func WithRevalidation

func WithRevalidation(ctx context.Context, cached *CachedResponse) context.Context

WithRevalidation returns a context whose trip sends the validators of cached, when Revalidable says its request may be conditional.

func WithTracePropagation

func WithTracePropagation(ctx context.Context, p TracePropagation) context.Context

WithTracePropagation returns a context whose trips' requests carry p.

Types

type CachedResponse

type CachedResponse struct {
	StatusCode int
	Headers    http.Header
	Body       []byte
}

CachedResponse is a response kept to be revalidated: what the target answered, before the decode converted its body or rewrote its headers. Nothing changes it once it is kept; a 304 makes a new one.

func KeepResponse

func KeepResponse(r *HTTPResponse) *CachedResponse

KeepResponse is what a response is kept as to be revalidated later, nil when it has no validator. The body is shared, not copied: nothing writes into a response's body, the decode replacing it rather than converting it in place (decode/textencoding.go).

func (*CachedResponse) Validators

func (r *CachedResponse) Validators() (etag, lastModified string)

Validators are the response's ETag and Last-Modified, as the target sent them; both empty when it has neither, and cannot be revalidated.

type CallAnswerError

type CallAnswerError struct{ Err error }

CallAnswerError is a gRPC call answered OK whose answer could not be used, such as one over the response limit once rendered as JSON. The call's status was OK, which GRPCStatusCode reports.

func (*CallAnswerError) Error

func (e *CallAnswerError) Error() string

func (*CallAnswerError) Unwrap

func (e *CallAnswerError) Unwrap() error

type CallStatusError

type CallStatusError struct {
	Code     int
	CodeName string
	Message  string
	// Err is what the error wraps: a context error when the deadline or a
	// cancellation ended the call, the limit error when the answer was too
	// large, or nil.
	Err error
}

CallStatusError is a gRPC call that ended with a status other than OK: Code is the status code's number, CodeName its name, such as UNAVAILABLE, and Message what the server, or the client library, said.

func (*CallStatusError) Error

func (e *CallStatusError) Error() string

func (*CallStatusError) Unwrap

func (e *CallStatusError) Unwrap() error

type DNSConfig

type DNSConfig struct {
	RecordType string `yaml:"record_type,omitempty"`
	Server     string `yaml:"server,omitempty"`
	Transport  string `yaml:"transport,omitempty"`
}

DNSConfig is a dns collector's own request keys: the record type asked for, A when left out; the server asked, host:port, the system's resolver when left out; and udp or tcp.

type DirectoryRead

type DirectoryRead struct {
	// Path is the directory, for logs.
	Path string
	// Files holds every matching file up to request.max_files, in name order.
	Files []FileRead
	// Matched counts the matching files; Skipped names those beyond
	// request.max_files, which were not looked at.
	Matched int
	Skipped []string
	// Bytes is how much was read across the files.
	Bytes int64
	// Listed counts the directory entries listed, and Truncated says the
	// listing stopped at its bound before the end of the directory.
	Listed    int
	Truncated bool
	// CutShort says the probe's deadline, or a shutdown, ended the read:
	// the files it had not read fail with that, and are no fault of theirs.
	CutShort bool
}

DirectoryRead is what reading a directory produced. It and FileRead live outside the localfile build tag because the probe and static target paths that consume them are shared by every request type.

type FastCGIConfig

type FastCGIConfig struct {
	DocumentRoot string            `yaml:"document_root,omitempty"`
	Params       map[string]string `yaml:"params,omitempty"`
}

FastCGIConfig is request.fastcgi: the directory the script's file is named in, SCRIPT_FILENAME being it and the URL's path, and parameters sent beside those made of the request, which replace one of theirs of the same name.

type FileRead

type FileRead struct {
	// Name is the file's name in the directory, its file label.
	Name     string
	ModTime  time.Time
	Response *HTTPResponse
	Err      error
}

FileRead is one file of a directory: a response to decode, or the reason there is none.

type GRPCConfig

type GRPCConfig struct {
	RPC              string            `yaml:"rpc"`
	Message          string            `yaml:"message"`
	Metadata         map[string]string `yaml:"metadata"`
	Descriptors      string            `yaml:"descriptors"`
	ProtosetFile     string            `yaml:"protoset_file"`
	ProtoFiles       []string          `yaml:"proto_files"`
	ProtoImportPaths []string          `yaml:"proto_import_paths"`
	AcceptCodes      []string          `yaml:"accept_codes"`
	// StreamMessages is how many messages of a server streaming method's
	// stream are read, at most; 0 calls unary methods alone.
	StreamMessages int `yaml:"stream_messages"`
}

GRPCConfig is a grpc collector's own request keys: the method called, package.Service/Method; the request message in the protobuf JSON mapping; the request metadata; where the message types come from, reflection, protoset (ProtosetFile) or proto (ProtoFiles, compiled with ProtoImportPaths); and the gRPC status codes, other than OK, whose calls are answers rather than failures, such as [NOT_FOUND].

type GraphiteConfig

type GraphiteConfig struct {
	Targets []string `yaml:"targets"`
	From    string   `yaml:"from"`
	Until   string   `yaml:"until"`
}

GraphiteConfig is a graphite collector's own request keys: the Graphite expressions asked of the render API, each sent as a target parameter, and the window they are rendered over.

type HTTPConfig

type HTTPConfig struct {
	Method     string                  `yaml:"method"`
	Body       string                  `yaml:"body"`
	Pagination *model.PaginationConfig `yaml:"pagination,omitempty"`
	// FastCGI is request.fastcgi, nil for none: the requests are sent to a
	// FastCGI application in place of an HTTP server (fastcgi.go).
	FastCGI *FastCGIConfig `yaml:"fastcgi,omitempty"`
}

HTTPConfig is an http collector's own request keys: the method, GET when left out; the body sent; the pagination that fetches the further pages of a paginated answer and merges them into one JSON document, the first page with its items array holding every page's items (pagination.go), nil when the answer is one page. request.unix_socket, which tcp takes too, is of the common part (model.RequestConfig).

type HTTPResponse

type HTTPResponse struct {
	StatusCode int
	// NoStatus says the answer has no status of its own, as a local file's
	// has not: StatusCode is only what lets it through the status check.
	NoStatus bool
	// GRPCCode is a grpc call's status code: 0 for OK, or a code the
	// collector accepts (request.accept_codes).
	GRPCCode  *int
	Headers   http.Header
	Body      []byte
	Target    string
	Collector string
	Duration  time.Duration
	// RedirectWithheld says where the answer came from when a redirect led
	// there and headers of the request were not sent to it, the host being
	// neither the request's own origin nor one of the collector's
	// request.redirect_trusted_hosts (redirecttrust.go), in the words the
	// error of a failing status goes on with: "from <host>, where a
	// redirect led: ..."; "" otherwise.
	RedirectWithheld string
	// NotRetried says why an answer of a retried status was not retried
	// with attempts left, in the words the error of its failing status
	// goes on with: under request.retry.retry_after, its Retry-After asked
	// for a wait longer than the probe's time left; "" otherwise.
	NotRetried string
	// Directory is set instead of Body by a localfile collector reading a
	// directory: every file it read, each to be decoded on its own.
	Directory *DirectoryRead
	// Rows is a sql collector's answer, the rows its statement returned,
	// each a map of its columns to their values, a column left out where
	// its value is NULL; Body is the same rows written as JSON, for what
	// shows an answer. The decoder hands Rows to the transforms as they are
	// (requesttype_sql.go).
	Rows []any
	// NamedRows is, of a sql collector of several statements
	// (request.statements), each one's rows, as Rows are, by its name; Rows
	// and Columns are then nil.
	NamedRows map[string]any
	// Columns is the names of a sql collector's columns, in the statement's
	// order, a column NULL in every row among them, which no row of Rows
	// has: a csv rule that reads one is then reading empty cells, not a
	// column the answer lacks.
	Columns []string
	// Pages is what an http collector's request.pagination fetched: each
	// page asked for, and whether it stopped at max_pages with another page
	// to come. Body is then the pages merged into one document, Headers
	// the first page's; or, when a page after the first was answered with
	// a status the collector does not accept, StatusCode, Headers and Body
	// are that page's (pagination.go). nil without request.pagination.
	Pages *PagesRead
	// Conditional says the request carried the validators of a cached
	// response (revalidate.go), and NotModified that the target answered
	// it 304 Not Modified: the response is then the cached one, its status
	// and body, with its headers updated from the 304's.
	Conditional, NotModified bool
	// Trip is what the request an http or graphite collector's answer
	// came from was besides its answer (HTTPTrip); nil for every other
	// request type, and for a response the debug page was given.
	Trip *HTTPTrip
}

HTTPResponse is what a fetch returned, whatever the request type: a status, headers and a body, or, for a localfile collector reading a directory, the files it read. Target and Collector say what was fetched, Duration how long it took.

func FetchCollector

func FetchCollector(ctx context.Context, target string, c *model.Collector, overrides RequestOverrides, forwarded http.Header) (*HTTPResponse, error)

FetchCollector gets a scrape's bytes the way the collector's type does.

func (*HTTPResponse) Status

func (r *HTTPResponse) Status() any

Status is the answer's status as rules read it, $status in jq and yq and response.status_code in Python: the HTTP status, a grpc call's status code, or nil for an answer without one, such as a local file's.

type HTTPTrip

type HTTPTrip struct {
	// DNS, Connect and TLS are how long the name's lookup, the connection
	// and the TLS handshake took, nil for a phase the request did not
	// have: on a connection it reused, none of them; over plain HTTP, no
	// handshake; to an IP address or a Unix socket, no lookup. Through a
	// proxy, the lookup and the connection are the proxy's, and the
	// handshake the target's through the tunnel, never the one with an
	// https:// proxy (proxyTLSDialer).
	DNS, Connect, TLS *time.Duration
	// FirstByte is the time from the request's start, when it asked for a
	// connection, to the first byte of the answer; nil for none.
	FirstByte *time.Duration
	// Total is the request's whole time, from its start to the end of
	// reading the body.
	Total time.Duration
	// TLSConnection is the TLS connection the request was sent on, nil
	// over plain HTTP.
	TLSConnection *TLSConnection
	// URL is the request's URL, where the redirects led, as it was sent:
	// ShownURL is what a rule reads of it. It is kept as it is, and shown
	// only when it is read, since most collectors' rules never read it.
	URL *url.URL
	// Redirects is how many redirects were followed to it, 0 for none.
	Redirects int
	// ProtoMajor and ProtoMinor are the version of HTTP the answer came
	// in, 1 and 1 for HTTP/1.1, 2 and 0 for HTTP/2; 0 and 0 for none.
	ProtoMajor, ProtoMinor int
	// RemoteIP is the address the request's connection was made to, the
	// zero Addr when it is not known: a request that was not traced (fetch
	// says when), one through a proxy, whose connection is to the proxy and
	// not to the target, and one over a Unix socket, which has no address.
	RemoteIP netip.Addr
}

HTTPTrip is what an http or graphite collector's answer says of the request that brought it, beside its status, headers and body: how long each phase of that request took, the TLS connection it was sent on, its URL and the redirects that led to it. It is of the request whose status the answer has: the last attempt of a retried trip, the request a redirect led to, a 304 that revalidated a cached response, and of a paginated trip the first page, or the page whose status failed it.

func (*HTTPTrip) JQHTTPVersion

func (t *HTTPTrip) JQHTTPVersion() any

JQHTTPVersion is the version of HTTP the answer came in, as jq's $http_version and Python's response.http_version have it: "1.0", "1.1" or "2", as blackbox_exporter's probe_http_version writes it; null for no trip.

func (*HTTPTrip) JQRedirects

func (t *HTTPTrip) JQRedirects() any

JQRedirects is the number of redirects as jq's $redirects and Python's response.redirects have it, null for no trip.

func (*HTTPTrip) JQRemoteIP

func (t *HTTPTrip) JQRemoteIP() any

JQRemoteIP is the address the request's connection was made to, as jq's $remote_ip and Python's response.remote_ip have it: "203.0.113.7" or "2001:db8::7", an IPv4 address that came as one mapped into IPv6 written as IPv4; null when it is not known (RemoteIP) and for no trip.

func (*HTTPTrip) JQTLS

func (t *HTTPTrip) JQTLS() any

JQTLS is the TLS connection as jq's $tls and Python's response.tls have it, null over plain HTTP and for no trip. The times are numbers, as $timings' are.

func (*HTTPTrip) JQTimings

func (t *HTTPTrip) JQTimings() any

JQTimings is the trip's phases as jq's $timings and Python's response.timings have them: seconds as numbers, null for a phase the request did not have, and null as a whole for no trip.

func (*HTTPTrip) JQURL

func (t *HTTPTrip) JQURL() any

JQURL is the URL as jq's $url and Python's response.url have it, null for no trip.

func (*HTTPTrip) ShownURL

func (t *HTTPTrip) ShownURL() string

ShownURL is the request's URL with its userinfo and fragment left out and the values of the query parameters whose names read as credentials masked, as a target is shown in a log line (MaskCredentialQueryValues); "" for none.

type HostRateLimitCount

type HostRateLimitCount struct {
	Name            string
	Waited, Refused uint64
	Since           time.Time
}

HostRateLimitCount is what an entry of rate_limits has counted: the requests that waited for their turn under it, those it refused, and when it began to count, the zero time for since the exporter started.

func HostRateLimitCounts

func HostRateLimitCounts() []HostRateLimitCount

HostRateLimitCounts reports the counts of every entry of rate_limits in force, in the configuration's order.

type ICMPConfig

type ICMPConfig struct {
	Count        int            `yaml:"count,omitempty"`
	Interval     model.Duration `yaml:"interval,omitempty"`
	ReplyTimeout model.Duration `yaml:"reply_timeout,omitempty"`
	PayloadBytes *int           `yaml:"payload_bytes,omitempty"`
	// AllAddresses pings every address of the target's name of the
	// families ip_family takes, at most icmpMaxAddresses of them, at once,
	// each in the document's addresses, the top of it of all of them.
	AllAddresses bool `yaml:"all_addresses,omitempty"`
}

ICMPConfig is an icmp collector's own request keys: how many echoes a scrape sends, 3 when left out, how long apart, 1s, how long the last one's reply is waited for, 1s, and how many bytes of data each carries, 56, as ping's.

type KubernetesConfig

type KubernetesConfig struct {
	Resource      string   `yaml:"resource,omitempty"`
	Group         string   `yaml:"group,omitempty"`
	Version       string   `yaml:"version,omitempty"`
	Namespaces    []string `yaml:"namespaces,omitempty"`
	AllNamespaces bool     `yaml:"all_namespaces,omitempty"`
	LabelSelector string   `yaml:"label_selector,omitempty"`
	FieldSelector string   `yaml:"field_selector,omitempty"`
	MaxObjects    int      `yaml:"max_objects,omitempty"`
	APIServer     string   `yaml:"api_server,omitempty"`
	// MetadataOnly lists the objects' metadata alone, a
	// PartialObjectMetadataList (docs/KUBERNETES.md#metadata-alone).
	MetadataOnly bool `yaml:"metadata_only,omitempty"`
	// Kubelet is what each node's kubelet is asked for, stats/summary, of a
	// listing of nodes (docs/KUBERNETES.md#kubelet-statistics);
	// KubeletViaAPIServer asks it through the API server's proxy of the
	// node, and KubeletCAFile is the CA the kubelets' certificates are
	// verified against when they are asked directly.
	Kubelet             string `yaml:"kubelet,omitempty"`
	KubeletViaAPIServer bool   `yaml:"kubelet_via_api_server,omitempty"`
	KubeletCAFile       string `yaml:"kubelet_ca_file,omitempty"`
}

KubernetesConfig is a kubernetes collector's own request keys: the objects listed, by the plural name of their resource, its API group, "" for the core group, and its version, v1 when left out; which of them are listed, by namespace and by selector; how many a listing may hold, 0 for the default; and the API server's URL when the exporter does not list its own cluster's; whether it lists the objects' metadata alone; and what each node's kubelet is asked for, of a listing of nodes.

type LDAPConfig

type LDAPConfig struct {
	BindDN   string       `yaml:"bind_dn,omitempty"`
	StartTLS bool         `yaml:"start_tls,omitempty"`
	Searches []LDAPSearch `yaml:"searches,omitempty"`
	// SASLExternal binds with SASL EXTERNAL: as the identity of the TLS
	// client certificate, with no DN or password sent.
	SASLExternal bool `yaml:"sasl_external,omitempty"`
}

LDAPConfig is an ldap collector's own request keys: the DN a simple bind is made as, none for an anonymous bind, whether TLS is begun with the StartTLS operation on a plaintext connection, and the searches whose results the document holds.

type LDAPSearch

type LDAPSearch struct {
	Name       string   `yaml:"name"`
	Base       string   `yaml:"base,omitempty"`
	Scope      string   `yaml:"scope,omitempty"`
	Filter     string   `yaml:"filter,omitempty"`
	Attributes []string `yaml:"attributes,omitempty"`
	CountOnly  bool     `yaml:"count_only,omitempty"`
	MaxEntries int      `yaml:"max_entries,omitempty"`
}

LDAPSearch is one entry of an ldap collector's request.searches: the name its result is put under in the document, where it searches, which entries it matches and what of them it reads. Scope "" is sub, Filter "" is (objectClass=*), no Attributes asks for the entries' DNs alone, and MaxEntries 0 is the default bound.

type MissingParamError

type MissingParamError struct{ Where, Name string }

MissingParamError is a placeholder with neither a value nor a default.

func (*MissingParamError) Error

func (e *MissingParamError) Error() string

type NTPConfig

type NTPConfig struct {
	Samples        int            `yaml:"samples,omitempty"`
	SampleInterval model.Duration `yaml:"sample_interval,omitempty"`
}

NTPConfig is an ntp collector's own keys: how many requests a scrape sends each server, samples, from 1 to ntpMaxSamples, and how long apart, sample_interval. The reply of the least delay is the server's answer, as NTP's clock filter takes it, and the spread of the offsets its jitter.

type PageRead

type PageRead struct {
	URL    string
	Status int
	Bytes  int
}

PageRead is one page request.pagination asked for: its URL, its status and the size of its body.

type PagesRead

type PagesRead struct {
	// Pages is every page asked for, in order, the first included.
	Pages []PageRead
	// MoreLeft says the trip stopped at request.pagination.max_pages while
	// the last page named another, or, for page and offset, held items.
	MoreLeft bool
	// Merged says the response is every page's, accepted, merged into one
	// document, or the first page alone when it was the only one; unset,
	// the response is that of the last page, whose status the collector
	// does not accept.
	Merged bool
}

PagesRead is what request.pagination fetched for one trip.

type PoolStats

type PoolStats struct {
	Idle              int
	Targets           int
	KeepaliveFailures uint64
	Rows              *int
}

PoolStats is what a collector's pools of connections hold: the connections idle in them, how many targets they are open to, how many keepalive checks of a connection failed, and the rows the last statement returned, Rows being set only once one has (a sql collector's, requesttype_sql.go).

func CollectorPools

func CollectorPools(requestType, collector string) PoolStats

CollectorPools reports what the pools of a collector of requestType hold (RequestType.ConnectionPools); nothing for a type that keeps none.

type ProxyRefusedError

type ProxyRefusedError struct {
	// Target is the host and port the tunnel was asked for.
	Target string
	// Status is the proxy's status line, such as 403 Forbidden.
	Status string
}

ProxyRefusedError is a proxy's refusal to tunnel to a target: its answer to the CONNECT of an https target other than 200. The status is the proxy's own words, which a probe's caller is not told (transportwithheld.go).

func (*ProxyRefusedError) Error

func (e *ProxyRefusedError) Error() string

type RedisCommand

type RedisCommand struct {
	Name    string   `yaml:"name"`
	Command []string `yaml:"command"`
}

RedisCommand is one entry of a redis collector's request.commands: the name its reply is put under in the document, and the command with its arguments, each argument sent as it is written, its placeholders filled.

type RedisConfig

type RedisConfig struct {
	DB           int            `yaml:"db,omitempty"`
	InfoSections []string       `yaml:"info_sections,omitempty"`
	Commands     []RedisCommand `yaml:"commands,omitempty"`
	Sentinel     *RedisSentinel `yaml:"sentinel,omitempty"`
}

RedisConfig is a redis collector's own request keys: the logical database selected, 0 when left out, the sections of INFO read, and the read-only commands whose replies the document holds besides.

type RedisSentinel

type RedisSentinel struct {
	Master       string `yaml:"master,omitempty"`
	Username     string `yaml:"username,omitempty"`
	PasswordFile string `yaml:"password_file,omitempty"`
}

RedisSentinel is a redis collector's request.sentinel: the name of the primary its target, a Sentinel, watches, and the Sentinel's own account, which is not the servers': the scrape asks the Sentinel which server is that primary now and reads that server.

type RequestKeyEntry

type RequestKeyEntry struct {
	Type, Key, GoType, Shape, Schema string
}

RequestKeyEntry is one key of a request type's own, as the catalogue holds it: the type, the key, the Go type of the field it is read into, as reflect names it and by its shape (GoTypeShape), and its configuration schema, as JSON.

func RequestKeyCatalogue

func RequestKeyCatalogue() []RequestKeyEntry

RequestKeyCatalogue is the catalogue of the own keys of every request type of the source tree (requestkeys_catalogue.go).

func UnbuiltRequestKeys

func UnbuiltRequestKeys() []RequestKeyEntry

UnbuiltRequestKeys are the entries of the catalogue of the types the build left out.

type RequestOverrides

type RequestOverrides struct {
	Method             string
	Path               string
	PathSet            bool
	Timeout            time.Duration
	Body               *string
	InsecureSkipVerify *bool
	RetryAttempts      *int
	// RetryNonIdempotent is a static target's retry.non_idempotent; no
	// probe parameter sets it.
	RetryNonIdempotent *bool
	RetryBackoff       *time.Duration
	FollowRedirects    *bool
	EnableHTTP2        *bool
	NewConnection      *bool
	// IPFamily is the ip_family probe parameter, or a static target's
	// request.ip_family, "" when neither sets it.
	IPFamily string
	// Targets, From and Until are a static target's request.targets, from
	// and until, replacing a graphite collector's; no probe parameter sets
	// them. Targets is nil when the target does not set it.
	Targets []string
	From    string
	Until   string
	// Message replaces a grpc collector's request.message: the message
	// probe parameter, or a static target's request.message. Metadata is a
	// static target's request.metadata, sent besides the collector's, and
	// RetryCodes its retry.codes; no probe parameter sets them.
	Message    *string
	Metadata   map[string]string
	RetryCodes []string
	// RetryStatuses is a static target's retry.statuses, replacing an http
	// or graphite collector's when not nil; no probe parameter sets it.
	RetryStatuses []string
	// RetryAfter is a static target's retry.retry_after; no probe
	// parameter sets it.
	RetryAfter *bool
	// AcceptStatus and AcceptCodes are a static target's request.accept_status
	// and accept_codes, replacing the collector's when not nil; no probe
	// parameter sets them.
	AcceptStatus []string
	AcceptCodes  []string
	// Username, BindDN and the credential files are a static target's
	// request.username, bind_dn, private_key_file, passphrase_file and
	// password_file, replacing an sshfile, sql, redis or ldap collector's
	// account, and TLS its request.tls, replacing a redis, ldap, tcp, sql,
	// grpc, http or graphite collector's whole block; no probe parameter sets them, so a
	// probe can neither choose the account a scrape logs in as nor the
	// certificate it presents.
	Username       string
	BindDN         string
	PrivateKeyFile string
	PassphraseFile string
	PasswordFile   string
	TLS            *model.TLSConfig
	// CommunityFile, AuthPasswordFile and PrivPasswordFile are a static
	// target's, replacing an snmp collector's community and v3 passwords,
	// and RequestTimeout and Retries its request.request_timeout and retries;
	// no probe parameter sets them.
	CommunityFile    string
	AuthPasswordFile string
	PrivPasswordFile string
	RequestTimeout   *time.Duration
	Retries          *int
	// SQLConnections is a static target's request.connections, whose keys
	// replace a sql collector's; no probe parameter sets it.
	SQLConnections *model.SQLConnections

	// Params are the param_<name> probe parameters, bound into the
	// {{param_<name>}} placeholders of the collector's request.path.
	Params map[string]string
	// Login is a static target's request.login, replacing an http or
	// graphite collector's; no probe parameter sets it, so a probe can
	// neither change where a login goes nor what it sends (login.go).
	Login *model.LoginConfig
	// RateLimit is a static target's request.rate_limit, replacing an
	// http or graphite collector's; no probe parameter sets it, so a probe
	// cannot ask a target faster than its configuration allows.
	RateLimit *model.RateLimitConfig
	// contains filtered or unexported fields
}

RequestOverrides are the probe parameters that change a collector's request for one probe. An unset field leaves the collector's setting in force.

func ParseRequestOverrides

func ParseRequestOverrides(values url.Values) (RequestOverrides, error)

ParseRequestOverrides reads the overrides from a probe's query parameters, refusing a malformed one.

func TargetOverrides

func TargetOverrides(t *model.StaticTarget) RequestOverrides

TargetOverrides translates the target request block into the same per-scrape override structure the /probe endpoint produces.

type RequestParam

type RequestParam struct {
	Name string
	// Required is set when some placeholder naming it has no default, so a
	// probe must supply it. Default is the first default given otherwise.
	Required bool
	Default  string
}

RequestParam is a parameter a collector takes from the probe, as param_<name>: the value a {{param_<name>}} placeholder of its request or of its label values is filled with.

func RequestParams

func RequestParams(c *model.Collector) []RequestParam

RequestParams lists the parameters a collector takes, in its request's path, templated body, headers and query values and in its label values (labelparams.go), sorted by name. A request whose placeholders cannot be parsed takes none; the configuration refuses it before it gets here.

type RequestParamsCheck

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

RequestParamsCheck is CheckRequestParams for many checks against the same collectors, as the check of a static target file against the configuration makes, one for each target: each collector's placeholders are found the first time it is checked, and kept for the checks after. Finding them again for every target cost a quarter of that check. A loaded collector does not change, and a RequestParamsCheck lives for one check of a file against one configuration, so what it keeps cannot go stale. Its zero value is ready to use; it is not safe for concurrent use.

func (*RequestParamsCheck) CheckRequestParams

func (check *RequestParamsCheck) CheckRequestParams(c *model.Collector, overrides RequestOverrides) (unused []string, err error)

CheckRequestParams is the package's CheckRequestParams, with the same results and errors, for a collector whose placeholders may have been found already by this check.

type RequestPolicy

type RequestPolicy struct {
	AcceptCodes []string
	Pagination  *model.PaginationConfig
	// UnixSocket is the http type's request.unix_socket, the socket every
	// request of the collector is sent over (unixsocket.go), "" for none.
	UnixSocket string
}

RequestPolicy is what a collector's request lets through, how it pages and where it is sent, that only some request types have (RequestType.Policy): the gRPC status codes, other than OK, whose calls are answers, the pagination of a paginated answer, its defaults filled in once validated, and the Unix socket an http collector's requests go to.

func CollectorPolicy

func CollectorPolicy(c *model.Collector) RequestPolicy

CollectorPolicy is what the request of c lets through that only its type has (RequestType.Policy); nothing for a type without it.

type RequestTrace

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

RequestTrace is the requests one trip sent, in order. spans says it is the trace of an exported trip's spans, which keeps no headers and is no debug run's.

func WithRequestTrace

func WithRequestTrace(ctx context.Context) (context.Context, *RequestTrace)

WithRequestTrace returns a context whose trips record their requests in the returned trace.

func WithSpanTrace

func WithSpanTrace(ctx context.Context) (context.Context, *RequestTrace)

WithSpanTrace returns a context whose trips record their requests in the returned trace as an exported trip's spans need them, without their headers, and are no debug run's.

func (*RequestTrace) Requests

func (t *RequestTrace) Requests() []TracedRequest

Requests returns the requests recorded so far.

type RequestType

type RequestType struct {
	Name string
	// Fields are the keys of model.RequestConfig's common part the type
	// accepts, those several types take; the keys only it takes are those
	// of Config.
	Fields []string
	// Config is the zero value of the struct the keys only this type takes
	// are read into, its own keys, each a field with its yaml key, which a
	// collector's request holds in Own (requestkeys.go). Nil for a type
	// whose keys are all of the common part.
	Config       any
	Overrides    []string // a name ending in "_" is a prefix, such as header_
	TargetFields []string
	Requester

	// OptionalTarget lets a probe or a static target leave target out.
	OptionalTarget bool
	// Stage names the fetch stage in logs and error bodies. Unset, "http".
	Stage string
	// CheckOverride lets a collector refuse a probe parameter, or a static
	// target's request key, that its type accepts but its configuration has
	// no use for, such as path for a localfile collector reading a directory.
	// Unset, everything the type accepts is accepted.
	CheckOverride func(c *model.Collector, key string) error
	// Query adds the query parameters the type builds itself to the URL
	// of a request made over HTTP, such as graphite's repeated target, which
	// request.query, one value to a name, cannot hold. They are the type's
	// alone: a pair of the target's own query that names one is dropped
	// (withoutQueryKeys). Unset, it adds none.
	Query func(c *model.Collector, overrides RequestOverrides) (url.Values, error)
	// ShownQuery says, of a query pair the type sets itself on a request,
	// its name and value as a server reads them, whether it was set from
	// the collector's configuration as its file writes it (writtenAsSent),
	// or is the exporter's own, such as graphite's format=json, so that a
	// debug report shows its value (ConfiguredQuery). Unset, the type sets
	// none, or none that is shown.
	ShownQuery func(c *model.Collector, name, value string) bool
	// CheckTargetRequest checks the values of a static target's request
	// block, where CheckOverride sees only its keys. Unset, any value of an
	// accepted key is accepted.
	CheckTargetRequest func(c *model.Collector, t *model.StaticTarget) error
	// CheckPath checks the value of the path probe parameter, which is
	// refused with what it returns, before anything is sent. Unset, the
	// value is checked when the request is made.
	CheckPath func(what, path string) error
	// CheckFiles reads the files a collector's request names, or a static
	// target's, when t is set, as a request would read them, and says what
	// a request would find wrong with them, for --dry-run. It is the check
	// of files read at a request, which the configuration's loading does not
	// read. Unset, nothing is read.
	CheckFiles func(c *model.Collector, t *model.StaticTarget) []string
	// DefaultApplies says whether a request key of a defaults block the
	// type takes, by its top name, applies to c as its own keys leave it:
	// dns takes tls for transport tls alone. Unset, every key it takes
	// applies.
	DefaultApplies func(c *model.Collector, key string) bool
	// URLPath says the type's path is a URL path, joined onto the target,
	// which can hold no query or fragment; localfile's is a file's.
	URLPath bool
	// StatusCodes says the type's answers carry gRPC status codes: it
	// retries by them, so request.retry takes codes, and not
	// non_idempotent, which is about HTTP methods, and its collectors
	// report the last one (GRPCStatusCode). Unset, it is the other way
	// round.
	StatusCodes bool
	// NamedFiles says which files a collector's request names that checking
	// it reads when the configuration loads, such as grpc's descriptor
	// files, for the watch of the configuration to stamp (NamedFiles).
	// Unset, it names none.
	NamedFiles func(c *model.Collector) []string
	// ReadFiles says which paths checking a collector's request looked at on
	// disk, the files the request names and those that reading them led to,
	// and gives a mark of that reading (ReadFiles). Unset, checking a
	// request reads no file but those it names.
	ReadFiles func(c *model.Collector) (paths []string, read string)
	// Follow is told the collectors and static targets in force whenever
	// the per-collector state follows a configuration (FollowConfiguration),
	// so a type that keeps connections across scrapes closes those nothing
	// in force uses any more. Unset, the type keeps none.
	Follow func(collectors []model.Collector, targets []model.StaticTarget)
	// CloseConnections closes every connection the type keeps, at shutdown.
	// Unset, it keeps none.
	CloseConnections func()
	// Connections reports, of a collector, the connections the type keeps
	// open for it now and how many it has made, for the type's own
	// self-metrics. Unset, the type keeps none.
	Connections func(collector string) (open int, made uint64)
	// ConnectionLimit reports, of a collector with a limit on its
	// connections, how many of its scrapes waited for room at the limit and
	// how many failed there. Unset, the type has no such limit.
	ConnectionLimit func(collector string) (waited, failed uint64)
	// ConnectionPools reports, of a collector, what the type's pools of
	// connections hold now (PoolStats). Unset, the type keeps no pools.
	ConnectionPools func(collector string) PoolStats
	// Policy gives what a collector's request lets through, and how it
	// pages, that only some types have, as --dry-run shows it beside what
	// every type's does (RequestPolicy). Unset, nothing.
	Policy func(c *model.Collector) RequestPolicy
	// MethodBody gives the method and the body of a collector's request
	// made over HTTP, as its configuration writes them, which the shared
	// request of http and graphite sends (fetch). Unset, none: the method
	// is the one the overrides carry, GET when they carry none, and there
	// is no body.
	MethodBody func(c *model.Collector) (method, body string)
	// Logins reports how many logins a collector's request.login made and
	// how many of them failed (login.go). Unset, the type does not log in.
	Logins func(collector string) (made, failed uint64)

	// Families are the per-collector self-metric families only the
	// collectors of this type have, beyond those its other settings give
	// it: http_exporter_targets_refused_total with the target lists
	// (Takes("allowed_targets")), the pagination families with
	// request.pagination, the login families with Logins, the rate limit
	// families with request.rate_limit and
	// http_exporter_scrape_grpc_status_code with StatusCodes.
	Families []string
	// Revalidates says an expired cached response of the type may be
	// revalidated with a conditional request (Revalidable).
	Revalidates bool
	// TargetHint names what a target of a collector of the type is, and
	// shows the forms it takes, as the collectors page and the debug page
	// ask for one: "URL" and "https://host:port", "Name to resolve" and
	// "the name to resolve, such as example.com". Each type says its own,
	// so a form never asks another type for an http target, and a type a
	// build leaves out takes its words with it. Required unless NoTarget
	// is set (registerRequestType).
	TargetHint func(c *model.Collector) (label, hint string)
	// NoTarget says the type takes no target at all: it reads what its
	// configuration names, and the collectors page and the debug page say
	// so in place of asking for one.
	NoTarget bool
	// AnswerHint says what a response of the type pasted on the debug page
	// is, as the body's field there asks for it: what the target answers,
	// for http; the rows as JSON, for sql. Required.
	AnswerHint string
	// JSONAnswer says the exporter makes the type's answer, a JSON document,
	// so its decoder is json and its transform one that reads JSON.
	JSONAnswer bool
	// JSONDocument says, for a type whose answer is a JSON document the
	// exporter makes on some collectors alone, what that document is when
	// a collector's answer is one, as a refusal of another decoder or
	// transform names it, and "" when it is not: a tcp collector with
	// request.document or request.connect_only. Such a collector is held to json and to the
	// transforms that read it, as one of a JSONAnswer type is.
	JSONDocument func(c *model.Collector) string
	// Decoder is the decoder a collector of the type uses when its
	// decoder.type is left out, rather than one chosen for each response.
	Decoder string
	// Rows says the type's answer is rows its driver read, value by value,
	// with no body to decode.
	Rows bool
	// FileExtensions says the type reads files, whose extension, rather
	// than a Content-Type, chooses the decoder of one left to choose.
	FileExtensions bool
	// Article is the article the type's name is read with in messages.
	// Unset, "an" before a vowel and "a" otherwise.
	Article string
	// KeyRules is what the configuration schema says of the type's own
	// keys beyond their Go types, by the path of each under the request
	// block, such as send or commands[].name: their descriptions, and any
	// pattern, bound or required key, as the rules of the configuration
	// schema are written. Unset, nothing.
	KeyRules func() map[string]map[string]any
	// SchemaRule is what the configuration schema holds a collector of the
	// type to beyond its keys: its required keys and the rules between
	// them, as Validate holds them. Unset, nothing more.
	SchemaRule func() map[string]any
	// UnusedParams words the refusal of probe parameters that nothing of a
	// collector uses (CheckPathParams), naming the places a placeholder of
	// the type can stand in (unusedParamsIn). Unset, they are http's: the
	// path, the body and the header and query values.
	UnusedParams func(c *model.Collector, overrides RequestOverrides, unused string) error
	// Templates lists the templated parts of a collector's request that are
	// the type's own, beyond the body, header and query values every type
	// may hold (requestTemplates). Unset, it has none.
	Templates func(c *model.Collector, overrides RequestOverrides) []templateField
	// KeyAdvice says, of a key of another type that a collector of this
	// type sets, which of the type's own keys does what the collector meant
	// it for, said after the refusal: ldap's start_tls for the starttls of
	// tcp and tlscert, which names a protocol ldap does not speak. Unset,
	// the refusal says nothing more.
	KeyAdvice map[string]string
}

RequestType is how one request.type reaches its data. Fields lists the keys of the common part it accepts and Config holds its own, Overrides the probe parameters that may change them and TargetFields the keys a static target may set; its Requester validates a collector's request, performs one, and says what a target is. Each type registers itself in RequestTypes.

What only some types have stays a field of its own, a hook left nil or a setting left zero by the types without it, rather than a method of Requester every type would implement to say it has nothing: an optional capability, which the core asks about only of a type that has it.

func OwnKeyTypes

func OwnKeyTypes() []*RequestType

OwnKeyTypes are the request types this binary was built with that take keys of their own (Config), in the order of the types of the tree.

func (*RequestType) Keys

func (rt *RequestType) Keys() []string

Keys are every request key the type accepts: the keys of the common part it lists (Fields) and those of its own struct.

func (*RequestType) OwnKeys

func (rt *RequestType) OwnKeys() []string

OwnKeys are the keys of the type's own struct (Config), in its order.

func (*RequestType) Takes

func (rt *RequestType) Takes(key string) bool

Takes reports whether the type accepts the request key.

type Requester

type Requester interface {
	// Validate checks a collector's request and fills in its defaults.
	Validate(c *model.Collector) error
	// Fetch performs one request of a collector.
	Fetch(ctx context.Context, target string, c *model.Collector, overrides RequestOverrides, forwarded http.Header) (*HTTPResponse, error)
	// CheckTarget validates a target before anything is fetched: a probe's
	// target, answered with 400 when it fails, and a static target's, at
	// load. static tells the two apart. A target left out is refused before
	// it is asked, unless the type has OptionalTarget.
	CheckTarget(c *model.Collector, target string, static bool) error
	// Label and Method give the url and http_method labels of the verbose
	// self-metrics.
	Label(target string, c *model.Collector, overrides RequestOverrides) (string, error)
	Method(c *model.Collector, overrides RequestOverrides) string
	// Display renders a target for logs, error bodies and the target label
	// of a static target's health series.
	Display(target string) string
}

Requester is what every request type does: each type's registration gives a small value implementing it (requesttype_<name>.go), whose methods are the type's own.

type S3FileConfig

type S3FileConfig struct {
	Region              string `yaml:"region,omitempty"`
	Endpoint            string `yaml:"endpoint,omitempty"`
	PathStyle           bool   `yaml:"path_style,omitempty"`
	AccessKeyIDFile     string `yaml:"access_key_id_file,omitempty"`
	SecretAccessKeyFile string `yaml:"secret_access_key_file,omitempty"`
	SessionTokenFile    string `yaml:"session_token_file,omitempty"`
	// Checksums is how the checksums the store keeps of an object are
	// checked as it is read: when_present, the default, required or off.
	Checksums string `yaml:"checksums,omitempty"`
}

S3FileConfig is an s3file collector's own request keys: the region requests are signed for, the URL of an S3-compatible store in place of AWS's, and whether the bucket is named in the URL's path rather than its host; and the files of static credentials, read at each request, without which the AWS SDK's default chain finds credentials.

type SNMPConfig

type SNMPConfig struct {
	// Version is 1, 2 for v2c, or 3; 2 when left out.
	Version int `yaml:"snmp_version,omitempty"`
	// CommunityFile is the file of v1's and v2c's community.
	CommunityFile string `yaml:"community_file,omitempty"`
	// SecurityLevel, AuthProtocol, AuthPasswordFile, PrivProtocol,
	// PrivPasswordFile and ContextName are a v3 user's.
	SecurityLevel    string `yaml:"security_level,omitempty"`
	AuthProtocol     string `yaml:"auth_protocol,omitempty"`
	AuthPasswordFile string `yaml:"auth_password_file,omitempty"`
	PrivProtocol     string `yaml:"priv_protocol,omitempty"`
	PrivPasswordFile string `yaml:"priv_password_file,omitempty"`
	ContextName      string `yaml:"context_name,omitempty"`
	// Get are the objects read one by one, by name; Walk the tables read
	// whole, each its columns by name.
	Get  map[string]string            `yaml:"get,omitempty"`
	Walk map[string]map[string]string `yaml:"walk,omitempty"`
	// Hex are the names, of get or table.column of walk, whose values are
	// written as hexadecimal bytes whatever they hold.
	Hex []string `yaml:"hex,omitempty"`
	// MaxRepetitions is how many values a GetBulk asks for; RequestTimeout
	// how long a request waits for its answer, and Retries how many times
	// one unanswered is sent again; WalkLimit the most values of a column.
	MaxRepetitions int            `yaml:"max_repetitions,omitempty"`
	RequestTimeout model.Duration `yaml:"request_timeout,omitempty"`
	Retries        *int           `yaml:"retries,omitempty"`
	WalkLimit      int            `yaml:"walk_limit,omitempty"`
}

SNMPConfig is an snmp collector's own request keys. The v3 user's name is request.username, of the common part.

type SQLConfig

type SQLConfig struct {
	Driver    string `yaml:"driver,omitempty"`
	Database  string `yaml:"database,omitempty"`
	Statement string `yaml:"statement,omitempty"`
	// StatementFile is the file the statement is read from, in place of
	// Statement, when the configuration loads (readSQLStatementFile); the
	// text read is statementText, which the statement run is.
	StatementFile string `yaml:"statement_file,omitempty"`

	Args []string `yaml:"args,omitempty"`
	// ArgTypes are the types args are bound as, one for each, by its
	// place: text, int, float or bool (sqlArgTypes). Left out, every arg
	// is bound as text.
	ArgTypes    []string              `yaml:"arg_types,omitempty"`
	Options     map[string]string     `yaml:"options,omitempty"`
	ServiceName string                `yaml:"service_name,omitempty"`
	MaxRows     int                   `yaml:"max_rows,omitempty"`
	Connections *model.SQLConnections `yaml:"connections,omitempty"`
	// Statements are several statements, each with its name and its own
	// args, run in order on one connection, in place of statement,
	// statement_file, args and arg_types: the document holds each one's
	// rows under its name (docs/SQL.md#several-statements).
	Statements []SQLStatement `yaml:"statements,omitempty"`
	// contains filtered or unexported fields
}

SQLConfig is a sql collector's own request keys: the database driver, the database, the one statement run and the values bound to its placeholders, the driver's allow-listed settings, and an Oracle database's service; the most rows a statement may return, 0 for the default; and how the type keeps connections to a target. The account and its credential files are of the common part, which other types take too.

func (SQLConfig) MarshalYAML

func (s SQLConfig) MarshalYAML() (any, error)

MarshalYAML writes the keys as a configuration writes them, and, for a statement read from statement_file, a digest of the text read: the YAML of a collector is what a reload compares to tell a changed collector and what a probe's cache key is made from (model.RequestConfig.MarshalYAML), and a statement file edited changes the collector as much as its statement edited in place would. Nothing reads the YAML back.

type SQLConnectInfo

type SQLConnectInfo struct {
	Driver, Host, Port, Account, Username, Password, Database, ServiceName string
	Options                                                                map[string]string
	TLS                                                                    bool
}

SQLConnectInfo is what a connection of the sql request type is made with, as a test's stand-in for the driver is given it (UseSQLTestDriver): the driver's name, the target, the account and the password read from its file, the database, the options and whether the connection uses TLS.

type SQLStatement

type SQLStatement struct {
	Name      string   `yaml:"name"`
	Statement string   `yaml:"statement"`
	Args      []string `yaml:"args,omitempty"`
	ArgTypes  []string `yaml:"arg_types,omitempty"`
}

SQLStatement is one entry of request.statements: its name, which its rows are under in the document, the statement, and the values bound to its placeholders, with their types, as request.args and request.arg_types are of a collector's one statement.

type SSHExecConfig

type SSHExecConfig struct {
	Command          []string `yaml:"command,omitempty"`
	SuccessExitCodes []int    `yaml:"success_exit_codes,omitempty"`
}

SSHExecConfig is an sshexec collector's own request keys: the command, its program first, and the exit statuses that are a success, 0 alone when empty.

type StageError

type StageError struct {
	Stage string
	Err   error
}

StageError is a fetch that failed before the target was asked, at a stage of its own, such as a grpc message that does not fit the method's input type: the stage is "message" rather than the type's fetch stage.

func (*StageError) Error

func (e *StageError) Error() string

func (*StageError) Unwrap

func (e *StageError) Unwrap() error

type TCPConfig

type TCPConfig struct {
	Greeting    string `yaml:"greeting,omitempty"`
	Send        string `yaml:"send,omitempty"`
	SendHex     string `yaml:"send_hex,omitempty"`
	Terminator  string `yaml:"terminator,omitempty"`
	AnswerBytes int    `yaml:"answer_bytes,omitempty"`
	UDP         bool   `yaml:"udp,omitempty"`
	Document    bool   `yaml:"document,omitempty"`
	// Steps are a conversation, in place of send and of where its answer
	// ends: each step's text written and its answer read until it matches
	// the step's until (tcpsteps.go).
	Steps []TCPStep `yaml:"steps,omitempty"`
	// ConnectOnly makes the scrape a check that the port takes a
	// connection: it dials, makes the TLS handshake with a tls block, and
	// closes, writing and reading nothing, its answer a JSON document of
	// whether it connected (tcpconnect.go). ConnectTimeout bounds the
	// connection and the handshake, and Ports are the ports of the target's
	// host dialed at once, in place of the target's port.
	ConnectOnly    bool           `yaml:"connect_only,omitempty"`
	ConnectTimeout model.Duration `yaml:"connect_timeout,omitempty"`
	Ports          []int          `yaml:"ports,omitempty"`
}

TCPConfig is a tcp collector's own request keys: the pattern the server's greeting must match, no greeting being read when empty, the text written once the connection is made, or once the greeting has come, nothing when empty, what the answer ends with, the answer ending when the server closes the connection when it is empty, and whether the answer is a JSON document of the exchange. request.starttls, which tlscert takes too, is of the common part (model.RequestConfig.StartTLS).

UDP sends send, or send_hex, as one datagram and takes the first datagram that comes back as the answer. SendHex is send as hexadecimal bytes, for a protocol whose requests are binary, and AnswerBytes a length the answer ends at, for one whose answers end neither with a terminator nor with the connection: Modbus TCP, whose server keeps the connection open and whose answer to a read is as long as the read asks.

type TCPStep

type TCPStep struct {
	Send  string `yaml:"send"`
	Until string `yaml:"until,omitempty"`
}

TCPStep is one step of request.steps: the text written, and the pattern its answer matches once it has all come.

type TLSConnection

type TLSConnection struct {
	// TLSVersion is the protocol's version as the tlscert document writes
	// it, "TLS 1.3".
	TLSVersion string
	// CipherSuite is the cipher suite's IANA name.
	CipherSuite string
	// ServerName is the name sent as SNI, "" when none was, as for an
	// IP address.
	ServerName string
	// Verified says the exporter verified the chain: false under
	// insecure_skip_verify.
	Verified bool
	// NotBefore and NotAfter are the leaf's validity, in Unix seconds.
	NotBefore, NotAfter int64
	// SubjectCN and IssuerCN are the common names of the leaf's subject
	// and issuer.
	SubjectCN, IssuerCN string
}

TLSConnection is what the exporter knows of a TLS connection to a target and of the certificate the target presented on it, nothing secret: the names follow the tlscert type's document (tls_version, cipher_suite, server_name, verified, not_before, not_after, subject_cn, issuer_cn), so a rule reads the two alike.

type TargetPrompt

type TargetPrompt struct {
	Label, Hint string
	None        bool
}

TargetPrompt is how a form asks for the target of a collector: Label and Hint as its type says them (RequestType.TargetHint), or None for a type that takes no target.

func TargetPromptOf

func TargetPromptOf(c *model.Collector) TargetPrompt

TargetPromptOf is how a form asks for the target of c; nothing for a type this build lacks.

type TargetRefusedError

type TargetRefusedError struct {
	Host   string
	Reason string
}

TargetRefusedError is a request refused by the collector's allowed_targets or denied_targets. The exporter answers it 403.

func (*TargetRefusedError) Error

func (e *TargetRefusedError) Error() string

func (*TargetRefusedError) Is

func (e *TargetRefusedError) Is(target error) bool

Is makes every TargetRefusedError match ErrTargetRefused.

type TraceFact

type TraceFact struct {
	Key    string
	Kind   TraceFactKind
	Int    int64
	Bool   bool
	Double float64
	// Name is a word the exporter chose from a set of its own, such as the
	// name it maps a status code to: never text the target sent, which a
	// span does not carry.
	Name string
}

TraceFact is one fact of TracedRequest.Facts, under Key: an integer, a boolean, a floating-point number or a name, as Kind says.

type TraceFactKind

type TraceFactKind uint8

TraceFactKind is which value of a TraceFact is its own.

const (
	TraceFactInt TraceFactKind = iota
	TraceFactBool
	TraceFactDouble
	TraceFactName
)

The kinds of TraceFact, which OTLP's attributes are of: intValue, boolValue, doubleValue and stringValue.

type TracePropagation

type TracePropagation struct {
	TraceID     [16]byte
	Sampled     bool
	State       string
	Parent      string
	ParentState string
}

TracePropagation is what a trip's requests carry under otlp.traces.propagate. TraceID set is a trace of the exporter's own: each request's traceparent names it, the request's own span id and, as Sampled says, the sampled flag, with State, when set, as its tracestate. TraceID zero passes Parent and ParentState, the caller's traceparent and tracestate, on as they came.

type TracedPhase

type TracedPhase struct {
	Name       string
	Start, End time.Time
}

TracedPhase is one phase of a request: an http request's dns, connect, tls or first_byte, or a connection's another type made for its request, connection.dns, connection.connect, connection.tls or connection.handshake (an SSH connection's), with when it began and ended.

type TracedRequest

type TracedRequest struct {
	Method string
	URL    string
	// Header is what went out, Host included when it was set.
	Header http.Header
	// Redirect is set on a request that followed a redirect.
	Redirect bool
	// Login is set on a request request.login made for its token, whose
	// body, holding the login's secrets, is never recorded (login.go).
	Login bool
	// Page is the page of request.pagination the request asked for, from
	// 1; 0 without request.pagination.
	Page int
	// Withheld names the headers of the first request that a redirect to a
	// host the collector does not trust was not sent (redirecttrust.go),
	// and WithheldWhy says why the redirect was not trusted.
	Withheld    []string
	WithheldWhy string
	// Outcome is how it ended: a status, a gRPC code, or the error, as a
	// debug report shows it. It may quote what the target sent — a
	// greeting, a command's stderr, a status line's reason — so a span,
	// which leaves the exporter as a log line does, never carries it: a
	// span has Failed and Facts instead.
	Outcome string
	// Failed says the request got no answer, or an answer its request type
	// takes for a failure: an error, or a connection lost before it was
	// answered. An HTTP answer's failure is its Status.
	Failed bool
	// Facts are what the request type tells of how the request ended, for
	// its span: numbers, yes-or-no answers and names of the exporter's own
	// vocabulary — a response code's, a TLS version's — that it worked out
	// of the answer, never text the target sent.
	Facts []TraceFact
	// Wait is, under request.retry.retry_after, how long the trip waited
	// before retrying the request and why, or why it was not retried when
	// a Retry-After asked for longer than its time left; and, under
	// request.rate_limit, how long the request waited for its turn before
	// it was sent; "" otherwise.
	Wait     string
	Duration time.Duration
	// Status is the HTTP status of the answer to an HTTP request, 0 for
	// one that got none and for a request of another type.
	Status int
	// RateLimitWait is how long the request waited for its turn under
	// request.rate_limit before it was sent.
	RateLimitWait time.Duration
	// Attempt is which attempt of the request it is under request.retry,
	// from 0; a redirect, a login and a page each begin at 0.
	Attempt int
	// SpanID is the span id the request was sent under in its traceparent
	// (otlp.traces.propagate), which its CLIENT span is made with; zero
	// when it sent none of the exporter's.
	SpanID [8]byte
	// Phases are the phases of an HTTP request that were timed, as
	// $timings has them (HTTPTrip): the name's lookup, the connection, the
	// TLS handshake, each only when the request made it, and the time to
	// the answer's first byte, from the request's start; or of a
	// connection another type made for the request (connTiming): its
	// lookup, connection and TLS or SSH handshake, without first_byte. nil
	// when none was, as for a request on a connection kept from before.
	Phases []TracedPhase
	// contains filtered or unexported fields
}

TracedRequest is one request a trip sent.

func (TracedRequest) Start

func (r TracedRequest) Start() time.Time

Start is when the request was sent: after any wait for its turn under request.rate_limit, which is no time the target took.

type TransportSettings

type TransportSettings struct {
	TLS         model.TLSConfig
	EnableHTTP2 bool
	// contains filtered or unexported fields
}

TransportSettings are what a connection pool depends on. Requests with the same settings share one pool.

type URLRedaction

type URLRedaction int

URLRedaction says what RedactURL does with a URL's query.

const (
	// DropQuery drops the query, the fragment and the userinfo, for a metric
	// label.
	DropQuery URLRedaction = iota
	// MaskQueryValues keeps each query parameter's name, as it was written
	// and where it stood, and masks its value, for a debug report, where
	// request.query may carry a token under any name. The fragment is
	// dropped.
	MaskQueryValues
	// MaskCredentialQueryValues masks the values of the query parameters
	// whose names read as credentials (CredentialName), and keeps the rest
	// as they are, in their order, for a displayed target: ?token=… is
	// withheld, and ?tenant=a and ?tenant=b stay two targets. The fragment
	// is dropped.
	MaskCredentialQueryValues
)

type URLTarget

type URLTarget struct{}

URLTarget is the part of a Requester of a type whose target is a URL, as http's and graphite's is: the url label is the URL the request is made to, its placeholders kept (requestLabel), http_method its method, and the target is displayed without credentials (safeTarget). A type embeds it and overrides what differs.

func (URLTarget) Display

func (URLTarget) Display(target string) string

Display is the target without credentials (safeTarget).

func (URLTarget) Label

func (URLTarget) Label(target string, c *model.Collector, overrides RequestOverrides) (string, error)

Label is the URL a request is made to (requestLabel).

func (URLTarget) Method

func (URLTarget) Method(c *model.Collector, overrides RequestOverrides) string

Method is the request's method (requestMethod).

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址