Class CarbonClient

Implementing of the graphite carbon plain text protocol.

Allowed Names and Values

This graphite carbon protocol implementation is a bit strict about the characters allowed in metric paths, tag names, and tag values just to be safe. The plain text protocol documentation itself isn't extremely precise and doesn't mention any allowed or disallowed characters or encoding schemes. Given the protocol just consists of lines in the form of <metric path> <metric value> <metric timestamp> it is clear that the path may not contain any whitespace. Also since the tags are just appended to the path name using ; as a delimiter between the path and the tags and = between tag name and value these characters can clearly also no occur in path names. Further the whisper server seems to store metric on the filesystem by splitting it on . and creating a filesystem hierarchy based on the split path comonents. That means paths better not contain any characters not allowed in file names of any common operating systems. Also no double-., leading-. or trailing-.. For tags there are also certain limitations around the ~ character.

Therefore this library only allows paths and tag names in this schema:

path           = path-component ('.' path-component)*
path-component = (letter | digit | '-' | '+' | '@' | '$' | '_' | hex-encoding)+

prefix         = path '.'?

tag-name       = path

tag-value      = (letter | digit | '-' | '+' | '@' | '$' | '_' | '.' | '*'
                 | ':' | ',' | '&' | '#' | '|' | '<' | '>' | '[' | ']'
                 | '(' | ')' | '{' | '}' | '=' | '!' | '?' | '^' | '/'
                 | '\' | hex-encoding)+

hex-encoding   = '%' hex-digit hex-digit
letter         = 'a' ... 'z' | 'A' ... 'Z'
digit          = '0' ... '9'
hex-digit      = '0' ... '9' | 'a' ... 'f' | 'A' ... 'F'

Note that tag values may not be empty.

The hex-encoding is meant as a convention. If you really have to use metric paths or tag names with other characters you can pass them through encodeURIComponent(). Note that you have to also do the reverse (decodeURIComponent()) when reading back metric paths, tag names and values.

Note that if the whisper server would really run on Windows (don't know if it ever does) there are also problems with case-insensitivity (also true for macOS) and for certain special file names: COM1 COM2 COM3 COM4 COM5 COM6 COM7 COM8 COM9 LPT1 LPT2 LPT3 LPT4 LPT5 LPT6 LPT7 LPT8 LPT9 CON NUL PRN

Also the tag name name is used to store the metric path.

This library does not take care of these cases.

See

Constructors

constructor

Properties

address autoConnect family? port prefix retryOnError retryTimeout sendBufferSize sendInterval transport udpSendBufferSize?

Accessors

bufferedBytes isBuffered isConnected isConnecting isDisconnected tlsCA tlsCert tlsKey

Methods

batchWrite connect disconnect flush off on once vbatchWrite vwrite write

Constructors

constructor

  • new CarbonClient(
        address: string,
        port?: number,
        transport?: IPTransport,
        autoConnect?: boolean,
    ): CarbonClient

  • Parameters

    • address: string

      hostname or IP address of carbon server

    • Optionalport: number

      port of carbon server, [[DEFAULT_PORT]] if not given

    • Optionaltransport: IPTransport

      transport layer protocol to use, [[DEFAULT_TRANSPORT]] if not given

    • OptionalautoConnect: boolean

      automatically connect on write if not connected, false if not given

    Returns CarbonClient

    Throws

    [[IllegalArgument]]

    Throws

    TypeError

  • new CarbonClient(
        path: string,
        transport: "IPC",
        autoConnect?: boolean,
    ): CarbonClient

  • Parameters

    • path: string

      path of Unix domain socket

    • transport: "IPC"

      always 'IPC'

    • OptionalautoConnect: boolean

      automatically connect on write if not connected, false if not given

    Returns CarbonClient

    Throws

    [[IllegalArgument]]

    Throws

    TypeError

  • new CarbonClient(options: CarbonClientOptions): CarbonClient

  • Parameters

    Returns CarbonClient

Properties

Readonlyaddress

address: string

For TCP and UDP the hostname or IP address of the server, for IPC the file name of the Unix domain socket.

autoConnect

autoConnect: boolean

Automatically connect on write if not connected.

Also if ture then calls of [[CarbonClient.connect]] when connected and calls of [[CarbonClient.disconnect]] when not connected are not errors.

Optional Readonlyfamily

family?: 4 | 6

For TCP and UDP the IP address family to use.

If not given it will be auto-detected. For UDP if there are IPv6 and IPv4 addresses of a hostname the IPv6 address will be preferred. Explicitely pass 4 if you do not want this.

Readonlyport

port: number

Server port to connect to. Will be -1 if [[CarbonClient.transport]] is 'IPC'.

Readonlyprefix

prefix: string = ''

Prefix added to all metric paths.

ReadonlyretryOnError

retryOnError: number = 0

Number of automatic retries on network error. Defaults to 0.

Error handlers are still called.

See

[[CarbonClient.retryTimeout]]

ReadonlyretryTimeout

retryTimeout: number = DEFAULT_RETRY_TIMEOUT

Time to wait before retrying after error. Defaults to [[DEFAULT_RETRY_TIMEOUT]].

See

[[CarbonClient.retryOnError]]

ReadonlysendBufferSize

sendBufferSize: number = DEFAULT_SEND_BUFFER_SIZE

Size of send buffer. If set to 0 metrics are sent immediately. Defaults to [[DEFAULT_SEND_BUFFER_SIZE]].

ReadonlysendInterval

sendInterval: number = DEFAULT_SEND_INTERVAL

Buffer wait time. If set to 0 metrics are sent immediately. Defaults to [[DEFAULT_SEND_INTERVAL]].

Readonlytransport

transport: Transport

Transport layer protocol to use.

Optional ReadonlyudpSendBufferSize

udpSendBufferSize?: number

If [[CarbonClient.transport]] is "UDP" the dgram.SocketOptions.sendBufferSize of UDP sockets.

Accessors

bufferedBytes

  • get bufferedBytes(): number

  • Returns the number of currently buffered bytes.

    If [[CarbonClient.isBuffered]] is false this is always 0.

    Returns number

isBuffered

  • get isBuffered(): boolean

  • Returns true if the client bufferes multiple writes into one send.

    Returns boolean

    See

    [[CarbonClient.sendBufferSize]] and [[CarbonClient.sendInterval]].

isConnected

  • get isConnected(): boolean

  • Returns true if the underlying socket was created, is writeable and not connecting.

    Returns boolean

isConnecting

  • get isConnecting(): boolean

  • Returns true if the underlying socket was created and is connecting or if the client is in the process of retrying to connect.

    Returns boolean

isDisconnected

  • get isDisconnected(): boolean

  • Returns true if the socket is destroyed, or if it is not yet created and not in the process of connecting.

    Returns boolean

tlsCA

  • get tlsCA(): null | readonly Buffer<ArrayBufferLike>[]

  • TLS certificate authoritie's certificate.

    Returns null | readonly Buffer<ArrayBufferLike>[]

tlsCert

  • get tlsCert(): null | readonly Buffer<ArrayBufferLike>[]

  • TLS client certificate.

    Returns null | readonly Buffer<ArrayBufferLike>[]

tlsKey

  • get tlsKey(): null | readonly Buffer<ArrayBufferLike>[]

  • TLS client private key.

    Returns null | readonly Buffer<ArrayBufferLike>[]

Methods

batchWrite

  • batchWrite(batch: MetricMap | MetricTuple[], timestamp?: Date): Promise<void>

  • Batch send multiple metrics all at once.

    If you use UDP keep batch sizes small enough to fit into one UDP packet!

    If timestamp is not provided the current time (via Date.now()) will be used.

    NOTE: If [[CarbonClient.sendBufferSize]] is > 0 then any error (except for [[IllegalArgument]]) might not happen during await of the returned Promise, but will only dispatched to any registered error handlers. See: [[CarbonClient.on]]

    Also note that if the sent data doesn't fit into the buffer, this will issue a send immediately and any promise rejections of that send will be directly returned when awaiting the returned Promise.

    Parameters

    • batch: MetricMap | MetricTuple[]

      The metrics to write.

    • Optionaltimestamp: Date

      The timestamp to use for metrics that don't define it directly.

    Returns Promise<void>

    Promise that resolves when the metric is sent.

    Throws

    [[IllegalArgument]] if a path, a timestamp, a tag-name, or a tag-value is invalid.

    Throws

    Error based on the errors that can be thrown by the underlying used NodeJS APIs.

connect

  • connect(): Promise<void>

  • Returns Promise<void>

  • connect(callback: (error: null | Error, retryCount: number) => void): void

  • Parameters

    • callback: (error: null | Error, retryCount: number) => void

    Returns void

disconnect

  • disconnect(callback: (error?: Error) => void): void

  • Disconnect the client from the server.

    NOTE: If you want currently buffered data to be sent before disconnect you need to call flush() first! Calling disconnect() cancels currently ongoing connection and send attempts.

    This alternative exists because awaiting promises on graceful shutdown seems to not work (the await never returns and the process just quits). Normal callbacks do work.

    Parameters

    • callback: (error?: Error) => void

      Async callback for when the client is disconnected or an error during disconnect occured.

    Returns void

    Throws

    Error if not connected and [[CarbonClient.autoConnect]] is false.

  • disconnect(): Promise<void>

  • Disconnect the client from the server.

    NOTE: If you want currently buffered data to be sent before disconnect you need to call flush() first! Calling disconnect() cancels currently ongoing connection and send attempts.

    Await the returned promise to wait for the disconnect to finish.

    Returns Promise<void>

    Throws

    [[NotConnected]] if not connected and [[CarbonClient.autoConnect]] is false.

    Throws

    Error based on the errors that can be thrown by the underlying used NodeJS APIs.

flush

  • flush(): Promise<void>

  • Returns Promise<void>

  • flush(callback: (error?: Error) => void): void

  • Parameters

    • callback: (error?: Error) => void

    Returns void

off

  • off(event: "connect", callback: () => void): void

  • Parameters

    • event: "connect"
    • callback: () => void

    Returns void

  • off(event: "error", callback: (error: Error) => void): void

  • Parameters

    • event: "error"
    • callback: (error: Error) => void

    Returns void

  • off(event: "close", callback: (hadError: boolean) => void): void

  • Parameters

    • event: "close"
    • callback: (hadError: boolean) => void

    Returns void

on

  • on(event: "connect", callback: () => void): void

  • Parameters

    • event: "connect"
    • callback: () => void

    Returns void

  • on(event: "error", callback: (error: Error) => void): void

  • Parameters

    • event: "error"
    • callback: (error: Error) => void

    Returns void

  • on(event: "close", callback: (hadError: boolean) => void): void

  • Parameters

    • event: "close"
    • callback: (hadError: boolean) => void

    Returns void

once

  • once(event: "connect", callback: () => void): void

  • Parameters

    • event: "connect"
    • callback: () => void

    Returns void

  • once(event: "error", callback: (error: Error) => void): void

  • Parameters

    • event: "error"
    • callback: (error: Error) => void

    Returns void

  • once(event: "close", callback: (hadError: boolean) => void): void

  • Parameters

    • event: "close"
    • callback: (hadError: boolean) => void

    Returns void

vbatchWrite

  • vbatchWrite(batch: MetricMap | MetricTuple[], timestamp?: Date): void

  • Batch send multiple metrics all at once.

    If you use UDP keep batch sizes small enough to fit into one UDP packet!

    If timestamp is not provided the current time (via Date.now()) will be used.

    In contrast to [[CarbonClient.batchWrite]] this doesn't return a promise, but instead if an error occurs during sending this error will be dispatched to any registered 'error' even handlers.

    Parameters

    • batch: MetricMap | MetricTuple[]

      The metrics to write.

    • Optionaltimestamp: Date

      The timestamp to use for metrics that don't define it directly.

    Returns void

vwrite

  • vwrite(path: string, value: number, timestamp: Date, tags?: Tags): void

  • Send a metric to the carbon server.

    In contrast to [[CarbonClient.write]] this doesn't return a promise, but instead if an error occurs during sending this error will be dispatched to any registered 'error' even handlers.

    Parameters

    • path: string

      Metric path.

    • value: number

      Metric value.

    • timestamp: Date

      Metric timestamp.

    • Optionaltags: Tags

      Metric tags.

    Returns void

  • vwrite(path: string, value: number, tags?: Tags): void

  • Send a metric to the carbon server.

    The current time (via Date.now()) will be used.

    In contrast to [[CarbonClient.write]] this doesn't return a promise, but instead if an error occurs during sending this error will be dispatched to any registered 'error' even handlers.

    Parameters

    • path: string

      Metric path.

    • value: number

      Metric value.

    • Optionaltags: Tags

      Metric tags.

    Returns void

write

  • write(path: string, value: number, timestamp: Date, tags?: Tags): Promise<void>

  • Send a metric to the carbon server.

    Parameters

    • path: string
    • value: number
    • timestamp: Date
    • Optionaltags: Tags

    Returns Promise<void>

    Promise that resolves when the metric is sent.

    Throws

    [[IllegalArgument]] if path, timestamp, a tag-name, or a tag-value is invalid.

    Throws

    [[NotConnected]] if not connected and [[CarbonClient.autoConnect]] is false.

    Throws

    [[SocketGone]] if socket went away during the operation.

    Throws

    Error based on the errors that can be thrown by the underlying used NodeJS APIs.

  • write(path: string, value: number, tags?: Tags): Promise<void>

  • Send a metric to the carbon server.

    The current time (via Date.now()) will be used.

    NOTE: If [[CarbonClient.sendBufferSize]] is > 0 then any error (except for [[IllegalArgument]]) might not happen during await of the returned Promise, but will only dispatched to any registered error handlers. See: [[CarbonClient.on]]

    Also note that if the sent data doesn't fit into the buffer, this will issue a send immediately and any promise rejections of that send will be directly returned when awaiting the returned Promise.

    Parameters

    • path: string
    • value: number
    • Optionaltags: Tags

    Returns Promise<void>

    Promise that resolves when the metric is sent.

    Throws

    [[IllegalArgument]] if path, a tag-name, or a tag-value is invalid.

    Throws

    [[NotConnected]] if not connected and [[CarbonClient.autoConnect]] is false.

    Throws

    [[SocketGone]] if socket went away during the operation.

    Throws

    Error based on the errors that can be thrown by the underlying used NodeJS APIs.

Settings

Member Visibility

On This Page

Allowed Names and Values
Constructors
Properties
Accessors
Methods