From 246c9c6edc82fb6f370756cd8bf5d92be59ff960 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= <freben@gmail.com>
Date: Mon, 1 Feb 2021 19:06:30 +0100
Subject: [PATCH] Update docs/plugins/observability.md

Co-authored-by: Adam Harvey <adam.harvey@dxc.com>
---
 .github/styles/vocab.txt      |  2 ++
 docs/plugins/observability.md | 35 ++++++++++++++++++++++++++++++++++-
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt
index d545b380f5..2991a6babd 100644
--- a/.github/styles/vocab.txt
+++ b/.github/styles/vocab.txt
@@ -218,6 +218,7 @@ Spotify
 sqlite
 squidfunk
 src
+stdout
 stefanalund
 subkey
 subtree
@@ -258,6 +259,7 @@ Voi
 Wealthsimple
 Weaveworks
 Webpack
+winston
 www
 WWW
 xyz
diff --git a/docs/plugins/observability.md b/docs/plugins/observability.md
index f52dd130bd..8b6668606f 100644
--- a/docs/plugins/observability.md
+++ b/docs/plugins/observability.md
@@ -5,7 +5,7 @@ title: Observability
 description: Adding Observability to Your Plugin
 ---
 
-This article briefly describes the observability option that are available to a
+This article briefly describes the observability options that are available to a
 Backstage integrator.
 
 ## Google Analytics
@@ -19,3 +19,36 @@ app:
 ```
 
 Replace the tracking ID with your own.
+
+For more information, learn about Google Analytics
+[here](https://marketingplatform.google.com/about/analytics/).
+
+## Logging
+
+The backend supplies a central [winston](https://github.com/winstonjs/winston)
+root logger that plugins are expected to use for their logging needs. In the
+default production setup, it emits structured JSON logs on stdout, with a field
+`"service": "backstage"` and also tagged on a per-plugin basis. Plugins that
+want to more finely specify what part of their processes that emitted the log
+message should add a `"component"` field to do so.
+
+An example log line could look as follows:
+
+```json
+{
+  "service": "backstage",
+  "type": "plugin",
+  "plugin": "catalog",
+  "component": "catalog-all-locations-refresh",
+  "level": "info",
+  "message": "Locations Refresh: Refreshing location bootstrap:bootstrap"
+}
+```
+
+## Health Checks
+
+The example backend in the Backstage repository
+[supplies](https://github.com/backstage/backstage/blob/bc18571b7a742863a770b2a54e785d6bbef7e184/packages/backend/src/index.ts#L99)
+a very basic health check endpoint on the `/healthcheck` route. You may add such
+a handler to your backend as well, and supply your own logic to it that fits
+your particular health checking needs.