1"use strict";(self.webpackChunkbackstage_microsite=self.webpackChunkbackstage_microsite||[]).push([["1677"],{447593(e,o,n){n.r(o),n.d(o,{assets:()=>a,contentTitle:()=>l,default:()=>g,frontMatter:()=>s,metadata:()=>r,toc:()=>c});var r=n(395107),t=n(474848),i=n(28453);let s={id:"root-logger",title:"Root Logger Service",sidebar_label:"Root Logger",description:"Documentation for the Root Logger service"},l,a={},c=[{value:"Root Logger",id:"root-logger",level:2},{value:"Configuring the service",id:"configuring-the-service",level:2},{value:"Configuration parameters",id:"configuration-parameters",level:3},{value:"Modifying the log level",id:"modifying-the-log-level",level:3},{value:"Overriding the default implementation",id:"overriding-the-default-implementation",level:3}];function d(e){let o={a:"a",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",ul:"ul",...(0,i.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(o.h2,{id:"root-logger",children:"Root Logger"}),"\n",(0,t.jsx)(o.p,{children:"The root logger is the logger that is used by other root services. It's where the implementation lies for creating child loggers around the backstage ecosystem including child loggers for plugins with the correct metadata and annotations."}),"\n",(0,t.jsx)(o.p,{children:"If you want to override the implementation for logging across all of the backend, this is the service that you should override."}),"\n",(0,t.jsx)(o.h2,{id:"configuring-the-service",children:"Configuring the service"}),"\n",(0,t.jsx)(o.h3,{id:"configuration-parameters",children:"Configuration parameters"}),"\n",(0,t.jsxs)(o.p,{children:["The Root Logger Service can be configured with the ",(0,t.jsx)(o.code,{children:"backend.logger"})," section of your ",(0,t.jsx)(o.code,{children:"app-config.yaml"}),"."]}),"\n",(0,t.jsx)(o.p,{children:"The following parameters are available:"}),"\n",(0,t.jsxs)(o.ul,{children:["\n",(0,t.jsxs)(o.li,{children:["\n",(0,t.jsxs)(o.p,{children:[(0,t.jsx)(o.code,{children:"level"})," (string, optional): Sets the global log level. Possible values are ",(0,t.jsx)(o.code,{children:"debug"}),", ",(0,t.jsx)(o.code,{children:"info"}),", ",(0,t.jsx)(o.code,{children:"warn"}),", or ",(0,t.jsx)(o.code,{children:"error"}),". Only messages at or above this level will be logged. This can also be set via the ",(0,t.jsx)(o.code,{children:"LOG_LEVEL"})," environment variable, which takes precedence. Defaults to ",(0,t.jsx)(o.code,{children:"info"}),". See ",(0,t.jsx)(o.a,{href:"#modifying-the-log-level",children:"Modifying the log level"}),"."]}),"\n"]}),"\n",(0,t.jsxs)(o.li,{children:["\n",(0,t.jsxs)(o.p,{children:[(0,t.jsx)(o.code,{children:"meta"})," (object, optional): Additional metadata to include with every log entry."]}),"\n"]}),"\n",(0,t.jsxs)(o.li,{children:["\n",(0,t.jsxs)(o.p,{children:[(0,t.jsx)(o.code,{children:"overrides"})," (array, optional): Allows to specify logger overrides for specific plugins or messages. Each override can match on plugin names, message patterns, or any field contained in the log, and set a custom log level for those matches."]}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(o.p,{children:["Log level overrides are useful for controlling the volume of logs generated in Backstage.\nThey allow you to apply a global log level, ",(0,t.jsx)(o.code,{children:"info"})," for example, while setting a stricter level, such as ",(0,t.jsx)(o.code,{children:"warn"}),", for specific verbose plugins."]}),"\n",(0,t.jsxs)(o.p,{children:["The reverse is also possible: you can set a global log level of ",(0,t.jsx)(o.code,{children:"warn"})," while enabling a more detailed level, such as ",(0,t.jsx)(o.code,{children:"debug"}),", for certain logs."]}),"\n",(0,t.jsx)(o.p,{children:"Example:"}),"\n",(0,t.jsx)(o.pre,{children:(0,t.jsx)(o.code,{className:"language-yaml",children:"backend:\n logger:\n meta:\n env: prod # Every log message will have `env=\"prod\"`\n\n level: info # Set the global log level to info (the default)\n\n overrides:\n # Set the log level to 'debug' for the catalog plugin logs\n - matchers:\n plugin: catalog\n level: debug\n\n # Ignore 'info' incoming HTTP requests logs from the rootHttpRouter service\n - matchers:\n service: rootHttpRouter\n type: incomingRequest\n level: warn\n\n # Ignore logs starting with \"Registered scheduled task\", unless they're warnings or errors\n - matchers:\n message: ['/^Registered scheduled task/']\n level: warn\n"})}),"\n",(0,t.jsx)(o.h3,{id:"modifying-the-log-level",children:"Modifying the log level"}),"\n",(0,t.jsx)(o.p,{children:"The available log levels, in order of decreasing verbosity, are:"}),"\n",(0,t.jsxs)(o.ul,{children:["\n",(0,t.jsxs)(o.li,{children:[(0,t.jsx)(o.code,{children:"debug"}),": Detailed information, typically useful only when troubleshooting."]}),"\n",(0,t.jsxs)(o.li,{children:[(0,t.jsx)(o.code,{children:"info"}),": General information about the application's operation. This is the default level."]}),"\n",(0,t.jsxs)(o.li,{children:[(0,t.jsx)(o.code,{children:"warn"}),": Indicates potential issues or situations that may require attention."]}),"\n",(0,t.jsxs)(o.li,{children:[(0,t.jsx)(o.code,{children:"error"}
1),": Indicates errors that have occurred but may not necessarily prevent the application from continuing."]}),"\n"]}),"\n",(0,t.jsxs)(o.p,{children:["The verbosity of the logging can be controlled by setting the log level. The log level determines the minimum severity level of events that will be output to the console. For example, if the log level is set to ",(0,t.jsx)(o.code,{children:"info"}),", events with a severity level of ",(0,t.jsx)(o.code,{children:"debug"})," will be ignored."]}),"\n",(0,t.jsxs)(o.p,{children:["To increase the log level, you can set the ",(0,t.jsx)(o.code,{children:"LOG_LEVEL"})," environment variable to a higher severity level, such as ",(0,t.jsx)(o.code,{children:"warn"})," or ",(0,t.jsx)(o.code,{children:"error"}),". However, be aware that increasing the log level might not result in more output if the existing code primarily emits logs at lower severity levels (e.g., ",(0,t.jsx)(o.code,{children:"debug"})," or ",(0,t.jsx)(o.code,{children:"info"}),"). In such cases, you may need to adjust the logging statements within the code to use higher severity levels to see more output."]}),"\n",(0,t.jsxs)(o.p,{children:["No additional steps are required beyond setting the ",(0,t.jsx)(o.code,{children:"LOG_LEVEL"})," environment variable, but the effectiveness depends on the existing logging statements in the code."]}),"\n",(0,t.jsxs)(o.p,{children:["To learn more, see the ",(0,t.jsx)(o.a,{href:"https://backstage.io/docs/tooling/local-dev/debugging",children:"Debugging Backstage"})," guide."]}),"\n",(0,t.jsx)(o.h3,{id:"overriding-the-default-implementation",children:"Overriding the default implementation"}),"\n",(0,t.jsx)(o.p,{children:"The following example is how you can override the root logger service to add additional metadata to all log lines."}),"\n",(0,t.jsx)(o.pre,{children:(0,t.jsx)(o.code,{className:"language-ts",children:"import { coreServices } from '@backstage/backend-plugin-api';\nimport { WinstonLogger } from '@backstage/backend-defaults/rootLogger';\nimport { createConfigSecretEnumerator } from '@backstage/backend-defaults/rootConfig';\n\nconst backend = createBackend();\n\nbackend.add(\n createServiceFactory({\n service: coreServices.rootLogger,\n deps: {\n config: coreServices.rootConfig,\n },\n async factory({ config }) {\n const logger = WinstonLogger.create({\n meta: {\n service: 'backstage',\n // here's some additional information that is not part of the\n // original implementation\n podName: 'myk8spod',\n },\n level: process.env.LOG_LEVEL || 'info',\n format:\n process.env.NODE_ENV === 'production'\n ? format.json()\n : WinstonLogger.colorFormat(),\n transports: [new transports.Console()],\n });\n\n const secretEnumerator = await createConfigSecretEnumerator({\n logger,\n });\n logger.addRedactions(secretEnumerator(config));\n config.subscribe?.(() => logger.addRedactions(secretEnumerator(config)));\n\n return logger;\n },\n }),\n);\n"})})]})}function g(e={}){let{wrapper:o}={...(0,i.R)(),...e.components};return o?(0,t.jsx)(o,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},28453(e,o,n){n.d(o,{R:()=>s,x:()=>l});var r=n(296540);let t={},i=r.createContext(t);function s(e){let o=r.useContext(i);return r.useMemo(function(){return"function"==typeof e?e(o):{...o,...e}},[o,e])}function l(e){let o;return o=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:s(e.components),r.createElement(i.Provider,{value:o},e.children)}},395107(e){e.exports=JSON.parse('{"id":"backend-system/core-services/root-logger","title":"Root Logger Service","description":"Documentation for the Root Logger service","source":"@site/versioned_docs/version-stable/backend-system/core-services/root-logger.md","sourceDirName":"backend-system/core-services","slug":"/backend-system/core-services/root-logger","permalink":"/docs/backend-system/core-services/root-logger","draft":false,"unlisted":false,"editUrl":"https://github.com/backstage/backstage/edit/master/docs/backend-system/core-services/root-logger.md","tags":[],"version":"stable","frontMatter":{"id":"root-logger","title":"Root Logger Service","sidebar_label":"Root Logger","description":"Documentation for the Root Logger service"},"sidebar":"docs","previous":{"title":"Root Lifecycle","permalink":"/docs/backend-system/core-services/root-lifecycle"},"next":{"title":"Scheduler","permalink":"/docs/backend-system/core-services/scheduler"}}')}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.