Environment-wide settings

Environment-wide settings are shared by every use of a plugin in the environment and are edited on the plugin's page.

In the console Environment-wide settingsEngine resource plugin_metadata

What an environment-wide settings is

Plugin metadata holds a plugin's environment-wide settings: one document per plugin, shared by every use of that plugin in the environment. Every route, service, plugin config and global rule that runs the plugin reads it. The console calls it Environment-wide settings and edits it on the plugin's own page.

It holds what a plugin reads for the whole environment, for example the fields of every record http-logger sends, or the address datadog sends its metrics to. It is not one of the places a plugin runs, described in Where a plugin runs: the settings add the plugin to no request.

When to use it

• Every record that http-logger sends, on every route, should carry the same fields: the client address, host, method, path, status and request time.
• Every route that sends metrics with datadog should send them to the one agent of the environment, named once.
• A change to the record a logger sends should reach every route that runs it at once, without editing each route.

Not for plugins that several routes share, each with settings of its own — see Plugin config (Plugin configs hold a set of plugins that several routes reference) or making a plugin run on every request of the environment — see Global rule (Global rules run their plugins on every request the engine handles).

Set it up

Shape every record the HTTP logger sends

request_time is in seconds with millisecond resolution, as the gateway measures it.

plugin_metadata · as the console saves it

{
  "id": "http-logger",
  "log_format": {
    "client_ip": "$remote_addr",
    "host": "$host",
    "method": "$request_method",
    "path": "$uri",
    "status": "$status",
    "request_time": "$request_time"
  }
}

Things to know

• With a log_format in the settings of http-logger, a route whose http-logger names no fields of its own sends records with those fields: the request path arrives under path.
• datadog on a route sends its metrics to the host and port its environment-wide settings hold, port 5140 in this example.
• The settings of a plugin that nothing runs are kept, and no request reads them until a route or a rule carries the plugin.
• Settings are checked against the plugin's own rules: a log_format for http-logger that is a line of text instead of a set of fields is refused when you save.
• Settings for a name that is no plugin are refused when you save.
• Resetting the settings removes them from the environment, and every use of the plugin takes the built-in values from its next request.
• Only roles that manage environment-wide settings can change them.
• AdviceTreat a change here as a change to every route that runs the plugin, and read on the plugin's page where it runs before you save.

Edited as Raw JSON

A plugin's metadata is edited on that plugin's own page; this object holds only the plugin's name, so it is edited here as JSON.