From 77fe4ef3cd107bd9ffc7acb505d1bf2dd4631747 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= <freben@gmail.com>
Date: Mon, 1 Feb 2021 17:09:03 +0100
Subject: [PATCH 1/2] docs: add a miniature article about observability

---
 docs/plugins/observability.md | 21 +++++++++++++++++++++
 microsite/sidebars.json       |  3 ++-
 mkdocs.yml                    |  1 +
 3 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100644 docs/plugins/observability.md

diff --git a/docs/plugins/observability.md b/docs/plugins/observability.md
new file mode 100644
index 0000000000..f52dd130bd
--- /dev/null
+++ b/docs/plugins/observability.md
@@ -0,0 +1,21 @@
+---
+id: observability
+title: Observability
+# prettier-ignore
+description: Adding Observability to Your Plugin
+---
+
+This article briefly describes the observability option that are available to a
+Backstage integrator.
+
+## Google Analytics
+
+There is a basic Google Analytics integration built into Backstage. You can
+enable it by adding the following to your app configuration:
+
+```yaml
+app:
+  googleAnalyticsTrackingId: UA-000000-0
+```
+
+Replace the tracking ID with your own.
diff --git a/microsite/sidebars.json b/microsite/sidebars.json
index f855327627..ebce8d900c 100644
--- a/microsite/sidebars.json
+++ b/microsite/sidebars.json
@@ -129,7 +129,8 @@
         "ids": [
           "plugins/publishing",
           "plugins/publish-private",
-          "plugins/add-to-marketplace"
+          "plugins/add-to-marketplace",
+          "plugins/observability"
         ]
       }
     ],
diff --git a/mkdocs.yml b/mkdocs.yml
index 6236d1c1a0..a303fd9978 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -80,6 +80,7 @@ nav:
       - Publishing:
           - Open source and npm: 'plugins/publishing.md'
           - Private/internal (non-open source): 'plugins/publish-private.md'
+          - Observability: 'plugins/observability.md'
   - Configuration:
       - Overview: 'conf/index.md'
       - Reading Configuration: 'conf/reading.md'

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 2/2] 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.