`
+
+
+Navigation
+----------
+
+Use the following syntax::
+
+ .. toctree::
+ :hidden:
+
+ sub-page1
+ sub-page2
+
+
+Lists
+-----
+
+1. Step 1
+
+ - Item 1
+
+ * Sub-item
+ - Item 2
+
+ i. Sub-step 1
+ #. Sub-step 2
+#. Step 2
+
+ a. Sub-step 1
+
+ - Item
+ #. Sub-step 2
+
+Term 1:
+ Definition
+Term 2:
+ Definition
+
+Tables
+------
+
++----------------------+------------+
+| Header 1 | Header 2 |
++======================+============+
+| Cell 1 | Cell 2 |
+| | |
+| Second paragraph | |
++----------------------+------------+
+| Cell 3 | Cell 4 |
++----------------------+------------+
+
++----------------------+------------------+
+| :center:`Header 1` | Header 2 |
++======================+==================+
+| Cell 1 | Cell 2 |
+| | |
+| Second paragraph | |
++----------------------+------------------+
+| Cell 3 | :center:`Cell 4` |
++----------------------+------------------+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Header 1
+ - Header 2
+ * - Cell 1
+
+ Second paragraph
+ - Cell 2
+ * - Cell 3
+ - Cell 4
+
+.. rst-class:: align-center
+
+ +----------------------+------------+
+ | Header 1 | Header 2 |
+ +======================+============+
+ | Cell 1 | Cell 2 |
+ | | |
+ | Second paragraph | |
+ +----------------------+------------+
+ | Cell 3 | Cell 4 |
+ +----------------------+------------+
+
+.. list-table::
+ :header-rows: 1
+ :align: center
+
+ * - Header 1
+ - Header 2
+ * - Cell 1
+
+ Second paragraph
+ - Cell 2
+ * - Cell 3
+ - Cell 4
+
+Notes
+-----
+
+.. note::
+ A note.
+
+.. tip::
+ A tip.
+
+.. important::
+ Important information
+
+.. caution::
+ This might damage your hardware!
+
+Images
+------
+
+.. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png
+
+.. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png
+ :width: 100px
+ :alt: Alt text
+
+ Figure caption
+
+Reuse
+-----
+
+.. |reuse_key| replace:: This is **included** text.
+
+|reuse_key|
+
+.. include:: index.rst
+ :start-after: include_start
+ :end-before: include_end
+
+Tabs
+----
+
+.. tabs::
+
+ .. group-tab:: Tab 1
+
+ Content Tab 1
+
+ .. group-tab:: Tab 2
+
+ Content Tab 2
+
+
+Glossary
+--------
+
+.. glossary::
+
+ example term
+ Definition of the example term.
+
+:term:`example term`
+
+More useful markup
+------------------
+
+- .. versionadded:: X.Y
+- | Line 1
+ | Line 2
+ | Line 3
+- .. This is a comment
+- :abbr:`API (Application Programming Interface)`
+
+----
+
+Custom extensions
+-----------------
+
+Related links at the top of the page::
+
+ :relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com)
+ :discourse: 12345
+
+Terms that should not be checked by the spelling checker: :spellexception:`PurposelyWrong`
+
+A single-line terminal view that separates input from output:
+
+.. terminal::
+ :input: command
+ :user: root
+ :host: vampyr
+ :dir: /home/user/directory/
+
+ the output
+
+A multi-line version of the same:
+
+.. terminal::
+ :user: root
+ :host: vampyr
+ :dir: /home/user/directory/
+
+ :input: command 1
+ output 1
+ :input: command 2
+ output 2
+
+A link to a YouTube video:
+
+.. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0
+ :title: Demo
+
+
+
+.. LINKS
+.. _Canonical website: https://canonical.com/
diff --git a/explanation/index.md b/explanation/index.md
new file mode 100644
index 000000000..ba10574c5
--- /dev/null
+++ b/explanation/index.md
@@ -0,0 +1,2 @@
+(exp)=
+# Explanation
diff --git a/how-to/index.md b/how-to/index.md
new file mode 100644
index 000000000..1c395857e
--- /dev/null
+++ b/how-to/index.md
@@ -0,0 +1,2 @@
+(howto)=
+# How-to guides
diff --git a/index.md b/index.md
new file mode 100644
index 000000000..b0c50d6a1
--- /dev/null
+++ b/index.md
@@ -0,0 +1,74 @@
+(home)=
+# Juju documentation
+
+Juju is an open-source ecosystem of tools designed to revolutionise the speed and quality of software operations on any cloud.
+
+When you do operations the Juju way, things are simple as `juju deploy`, `juju configure`, `juju integrate...`, `juju scale...`, `juju upgrade`, etc. – for any charmed application (i.e., application equipped with operations code for use with Juju) on any type of supported cloud (Kubernetes or otherwise).
+
+> [Browse existing charms on Charmhub](https://charmhub.io/) [Browse supported clouds](https://juju.is/docs/juju/juju-supported-clouds)
+
+At a time when operations code is still largely stuck with handcrafted code, YAML, or Kubernetes-only operators, the Juju paradigm offers reusable code, testable operations, and multicloud, so you can achieve a lot more, a lot better, and a lot faster.
+
+> [Did you know? Juju also has an integration with Terraform!](https://juju.is/docs/juju/terraform-juju-client)
+
+Whether you are a developer wondering how to make your application ready for the cloud, a cloud system administrator or an SRE tired of YAML, or a business owner, Juju can help.
+
+
+
+
+---
+
+## In this documentation
+
+````{grid} 1 1 2 2
+
+```{grid-item} [Tutorial](/tutorial/get_started)
+
+**Start here**: a hands-on introduction to Juju for new users
+```
+
+```{grid-item} [How-to guides](/how-to/index)
+
+**Step-by-step guides** covering key operations and common tasks
+```
+
+````
+
+````{grid} 1 1 2 2
+:reverse:
+
+```{grid-item} [Reference](/reference/index)
+
+**Technical information** - specifications, APIs, architecture
+```
+
+```{grid-item} [Explanation](/explanation/index)
+
+**Discussion and clarification** of key topics
+```
+
+````
+
+---
+
+## Project and community
+
+Juju is a member of the Ubuntu family. It’s an open source project that warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback.
+
+* [Code of conduct](https://ubuntu.com/community/ethos/code-of-conduct)
+* [Join our online forum](https://discourse.charmhub.io/)
+* [Join our online chat](https://matrix.to/#/#charmhub-juju:ubuntu.com)
+* Contribute
+* Roadmap
+* Thinking about using Juju for your next project? Get in touch!
+
+
+
+```{toctree}
+:hidden:
+:maxdepth: 2
+
+Tutorial
+How-to guides
+Reference
+Explanation
diff --git a/make.bat b/make.bat
new file mode 100644
index 000000000..32bb24529
--- /dev/null
+++ b/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.https://www.sphinx-doc.org/
+ exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/reference/index.md b/reference/index.md
new file mode 100644
index 000000000..1f1d06a5c
--- /dev/null
+++ b/reference/index.md
@@ -0,0 +1,2 @@
+(ref)=
+# Reference
diff --git a/reuse/links.txt b/reuse/links.txt
new file mode 100644
index 000000000..f9d3d5cdc
--- /dev/null
+++ b/reuse/links.txt
@@ -0,0 +1 @@
+.. _link text: https://example.com
diff --git a/tmp/t/10211.md b/tmp/t/10211.md
new file mode 100644
index 000000000..2767d3c5a
--- /dev/null
+++ b/tmp/t/10211.md
@@ -0,0 +1,54 @@
+[note type=caution]
+The information in this doc is based on Juju version 3.5.5,
+and may not accurately reflect other versions of Juju.
+[/note]
+
+> See also: [create-storage-pool](/t/10093), [remove-storage-pool](/t/10068)
+**Alias:** storage-pools
+
+## Summary
+List storage pools.
+
+### Options
+| Flag | Default | Usage |
+| --- | --- | --- |
+| `-B`, `--no-browser-login` | false | Do not use web browser for authentication |
+| `--format` | tabular | Specify output format (json|tabular|yaml) |
+| `-m`, `--model` | | Model to operate in. Accepts [<controller name>:]<model name>|<model UUID> |
+| `--name` | | Only show pools with these names |
+| `-o`, `--output` | | Specify an output file |
+| `--provider` | | Only show pools of these provider types |
+
+## Examples
+
+List all storage pools:
+
+ juju storage-pools
+
+List only pools of type kubernetes, azure, ebs:
+
+ juju storage-pools --provider kubernetes,azure,ebs
+
+List only pools named pool1 and pool2:
+
+ juju storage-pools --name pool1,pool2
+
+
+## Details
+
+The user can filter on pool type, name.
+
+If no filter is specified, all current pools are listed.
+If at least 1 name and type is specified, only pools that match both a name
+AND a type from criteria are listed.
+If only names are specified, only mentioned pools will be listed.
+If only types are specified, all pools of the specified types will be listed.
+
+Both pool types and names must be valid.
+Valid pool types are pool types that are registered for Juju model.
+
+
+---
+
+-------------------------
+
diff --git a/tmp/t/12-factor-app-charm.md b/tmp/t/12-factor-app-charm.md
new file mode 100644
index 000000000..48235a886
--- /dev/null
+++ b/tmp/t/12-factor-app-charm.md
@@ -0,0 +1,23 @@
+(12-factor-app-charm)=
+# 12-Factor app charm
+
+A **12-Factor app charm** is a {ref}`charm ` that has been created using certain coordinated pairs of {ref}`Rockcraft ` and {ref}`Charmcraft ` {ref}`profiles ` designed to give you most of the content you will need to generate a [rock^](https://documentation.ubuntu.com/rockcraft/en/latest/explanation/rocks/) for a charm, and then the charm itself, for a particular type of workload (e.g., an application developed with Flask).
+
+```{tip}
+
+**Did you know?** The OCI images produced by the 12-Factor-app-geared Rockcraft extension are designed to work standalone and are also well integrated with the rest of the Flask framework tooling.
+
+```
+
+When you initialise a rock with a 12-Factor-app-charm-geared profile, the initialisation will generate all the basic structure and content you'll need for the rock, including a [`rockcraft.yaml`^](https://canonical-rockcraft.readthedocs-hosted.com/en/latest/reference/rockcraft.yaml/#) prepopulated with an extension matching the profile. Similarly, when you initialise a charm with a 12-Factor-app-charm-geared profile, that will generate all the basic structure content you'll need for the charm, including a {ref}``charmcraft.yaml` ` pre-populated with an extension matching the profile as well as a `src/charm.py` pre-loaded with a library (`paas_charm`) with constructs matching the profile and the extension.
+
+
+At present, there are four pairs of profiles:
+- `flask-framework` ({ref}`Rockcraft extension 'flask-framework' `, {ref}`Charmcraft extension 'flask-framework' `)
+- `django-framework` ({ref}`Rockcraft extension 'django-framework' `, {ref}`Charmcraft extension 'django-framework' `)
+- `fastapi-framework` ({ref}`Rockcraft extension 'fastapi-framework' `, {ref}`Charmcraft extension 'fastapi-framework' `)
+- `go-framework` (Rockcraft extension 'go-framework', {ref}`Charmcraft extension 'go-framework' `)
+
+
+
+> **Contributors:** @econley, @jdkandersson, @javierdelapuente, @tmihoc
\ No newline at end of file
diff --git a/tmp/t/about-application-modelling.md b/tmp/t/about-application-modelling.md
new file mode 100644
index 000000000..d1d65c169
--- /dev/null
+++ b/tmp/t/about-application-modelling.md
@@ -0,0 +1,32 @@
+(about-application-modelling)=
+# About application modelling
+
+> See also: {ref}`Application `, {ref}`Model `
+
+Juju provides simplicity, stability and security. Models reduce the cognitive gap between the whiteboard picture of your service and how it is implemented. An application model is a definition of which applications are providing a service and how they inter-relate.
+
+Technical details such as CPU core counts, disk write throughput, and IP addresses are secondary. They are accessible to administrators, but an application model places the applications at the front.
+
+The primary function of a model is to enable you to maintain an uncluttered view of your service. Operational simplicity improves communication and understanding. Models provide an abstract view of the infrastructure that's hosting your service.
+
+More specifically, advantages include:
+
+
+### A. Service isolation
+
+Juju models enforce service isolation. A model maintains exclusive access of the resources under its control.
+
+
+### B. Access control
+
+Models provide access control. Juju enables you to create user accounts that have limited ability to alter the deployment.
+
+
+### C. Repeatability
+
+Models provide repeatable infrastructure deployments. Once your model is in-place and functional, it becomes simple to export a model's definition as a bundle, then re-deploy that model in another host.
+
+
+### D. Boundaries
+
+Models respect bureaucratic boundaries. Models enable you to partition compute resources according to your internal guidelines. You may wish to keep a central set of databases in the same model. Juju's access controls are model-specific, enabling you to know exactly who has permissions to perform direct database administration. Those databases could be made available to various consuming applications from other models via relations (which can span models). Other use cases for central models include secrets (using the [vault charm](https://jaas.ai/vault/)) and identity management (using the [keystone charm](https://jaas.ai/keystone)).
\ No newline at end of file
diff --git a/tmp/t/about-charming-history.md b/tmp/t/about-charming-history.md
new file mode 100644
index 000000000..edf63ca64
--- /dev/null
+++ b/tmp/t/about-charming-history.md
@@ -0,0 +1,46 @@
+(about-charming-history)=
+# About charming history
+
+Since its beginnings in 2009, the writing of charms has gone through multiple phases, comprising three different frameworks based on three different libraries. This document explains this evolution.
+
+
+**Contents:**
+
+- [Background](#heading--background)
+- [2014: The Services Framework](#heading---the-services-framework)
+- [2015: The Reactive Framework](#heading---the-reactive-framework)
+- [2019 - Present: The Operator Framework Ops](#heading--2019---present-the-operator-framework-ops)
+
+Background
+
+Juju was initially conceived in 2009 by Mark Shuttleworth, Gustavo Niemeyer and Simon Wardley [[1](https://blog.labix.org/2013/06/25/the-heart-of-juju)] as a way to simplify the deployment and operation of applications and their supporting services. Juju enables users to both graphically and non-graphically model complex deployments which are composed using one or more Charms - reusable packages that contain all the instructions necessary to deploy, configure, operate and integrate software.
+
+The Juju team adopted the Go language early-on, noting its suitability to cloud-first environments. This is an observation that has been made by numerous subsequent cloud-native projects - [Kubernetes](https://kubernetes.io/), [Terraform](https://terraform.io), [containerd](https://containerd.io/) to name just a few.
+
+Juju has evolved significantly over time, and throughout its life a number of frameworks and libraries have been authored to simplify and standardise the way Charms are written. One thing that hasn't changed throughout time however, is the approach that Juju takes to operating workloads - Juju's fundamentally works just like it did in 2009, but now supports many more underlying compute platforms (such as Kubernetes).
+
+Charms can be written in any language - that was as true in 2009 as it is today. Over time however, the Charming community has settled on Python as its language of choice. Python is extremely popular, has a huge community and is already commonly used to perform system automation tasks, making it a great choice for authoring Charms and for ensuring re-usability among the charming community.
+
+2014: The Services Framework
+
+
+The Services Framework evolved from the [charmhelpers](https://github.com/juju/charm-helpers) library; it aimed to standardise an approach to event handling and Charm structure. The services framework provided the first steps toward more declarative operators, and more consistency across the charm landscape.
+
+2015: The Reactive Framework
+
+
+Derived from [reactive programming](https://en.wikipedia.org/wiki/Reactive_programming), the [charms.reactive](https://charmsreactive.readthedocs.io/) library was first announced on the [Ubuntu Blog](https://ubuntu.com/blog/charming-2-0-now-with-100-more-awesome). It enabled developers to continue authoring Charm actions in the familiar “hook contexts” that were fundamental to the Services Framework, but favoured an event driven approach that simplified the development of charms. The Reactive framework also saw the introduction of *layers*, which could be reused and composed into new charms.
+
+2019 - Present: The Operator Framework Ops
+
+The latest and most current framework is the [Ops Framework](https://github.com/canonical/operator), which was released with initial focus on enabling the development of charms for Kubernetes, while also simplifying the development of charms for other substrates. This framework provides a single library for developers to target when authoring charms for any substrate. The Ops Framework extends the operator pattern beyond Kubernetes and into multi-cloud, multi-substrate application management.
+
+The Ops Framework is event driven and implements the [observer pattern](https://en.wikipedia.org/wiki/Observer_pattern). The Juju controller emits events that charms observe and respond to at key points during an application’s [lifecycle](https://juju.is/docs/sdk/events). In-keeping with the goal of enabling developers to share and reuse quality, reviewed operator code, the Ops Framework introduced the concept of charm [libraries](https://juju.is/docs/sdk/libraries).
+
+In addition to the new framework, a new tool was introduced named [`charmcraft`](https://github.com/canonical/charmcraft), which enables developers to easily create new charms (templated for use with the Ops Framework), and publish/release charms to the [Charmhub](https://charmhub.io) - the home of the Open Operator Collection.
+
+The Ops Framework, in combination with Charmcraft, is the recommended way to write charms now. However, charms previously written using other frameworks and libraries will continue to work.
+
+
\ No newline at end of file
diff --git a/tmp/t/action.md b/tmp/t/action.md
new file mode 100644
index 000000000..1a1cec356
--- /dev/null
+++ b/tmp/t/action.md
@@ -0,0 +1,88 @@
+(action)=
+# Action
+
+
+
+> See also: {ref}`How to manage actions `
+
+In Juju, an **action** is a script that is triggered via {ref}`the `juju` CLI client ` and applied to a {ref}`unit `. It contains a list of commands defined by a {ref}`charm ` to allow a {ref}`user ` with the right {ref}`access level ` to interact with an {ref}`application ` in ways specific to the application. This may include anything from creating a snapshot of a database, adding a user to a system, dumping debug information, etc.
+
+> See examples: [Charmhub | `kafka` > Actions](https://charmhub.io/kafka/actions), [Charmhub | `prometheus-k8s` > Actions](https://charmhub.io/prometheus-k8s/actions), etc.
+
+
+
+(Starting with `juju v.3.0`: )
+ Actions are identified by integers (instead of [UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier)).
+
+(Starting with `juju v.3.0`: ) Running an action defaults to waiting for the output before returning. This synchronous behaviour allows actions to be easily included in command-line pipelines.
+
+(Starting with `juju v.3.0`: ) The execution of an action is organised into {ref}`tasks ` and {ref}`operations `. (If an action defines a named unit of work -- e.g., back up the database -- that can be executed on selected units, a task is the execution of the action on each target unit, and an operation is the group of tasks queued by running an action across one or more units.)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/tmp/t/add-alert-rules.md b/tmp/t/add-alert-rules.md
new file mode 100644
index 000000000..5b1562929
--- /dev/null
+++ b/tmp/t/add-alert-rules.md
@@ -0,0 +1,37 @@
+(add-alert-rules)=
+# Add alert rules
+
+Support for providing alert rules through the relation is available for [`loki-k8s`](https://charmhub.io/loki-k8s) and [`prometheus-k8s`](https://charmhub.io/prometheus-k8s), both directly and through intermediary charms like [`grafana-agent-k8s`](https://charmhub.io/grafana-agent-k8s) and [`prometheus-scrape-config-k8s`](https://charmhub.io/prometheus-scrape-config-k8s).
+
+### Prerequisites
+To be able to pass on alert rules, you also need to implement their corresponding telemetry relation interface, as well as instantiating their corresponding library classes. For Prometheus, the relation interface is either `prometheus_scrape` and `MetricsEndpointProvider`, or `prometheus_remote_write` and `RemoteWriteConsumer`. For Loki, this is `loki_push_api` and either `LokiPushApiConsumer` or `LogProxyConsumer`. If both interfaces are implemented, it would roughly look as follows:
+
+```
+provides:
+ metrics-endpoint:
+ interface: prometheus_scrape
+
+requires:
+ logging:
+ interface: loki_push_api
+```
+
+### Create an alert rule
+An alert rule consists of a name, an expression, a duration, as well as optionally a set of labels and annotations. In this how to, we'll use an alert rule for `zinc-k8s`. For the sake of this how to, the details of the rule are of less importance. If you want to learn more about crafting alert rules, have a look at the official [Prometheus](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/) or [Loki](https://grafana.com/docs/loki/latest/rules/#example) documentation.
+
+```yaml
+alert: ZincTargetMissing
+expr: up == 0
+for: 0m
+labels:
+ severity: critical
+annotations:
+ summary: Prometheus target missing (instance {{ $labels.instance }})
+ description: |
+ A Prometheus target has disappeared. An exporter might be crashed.
+ VALUE = {{ $value }}\n LABELS = {{ $labels }}
+```
+
+Save the file in `./src/prometheus_alert_rules` for Prometheus, or `./src/loki_alert_rules` for Loki, using a file name ending with `.rule`. Next time you pack and deploy your charm, the alert rules will be transferred over as you integrate it with something using a supported relation interface.
+
+> Note: Custom paths must be passed as an argument to the constructor (e.g. `alert_rules_path=./src/rules/loki`).
\ No newline at end of file
diff --git a/tmp/t/agent-introspection-juju_engine_report.md b/tmp/t/agent-introspection-juju_engine_report.md
new file mode 100644
index 000000000..43b696bcd
--- /dev/null
+++ b/tmp/t/agent-introspection-juju_engine_report.md
@@ -0,0 +1,102 @@
+(agent-introspection-juju_engine_report)=
+# Agent introspection: juju_engine_report
+
+> See also: {ref}`Agent introspection `
+
+The engine report is a window into the internals of the agent. This is primarily useful to developers to help debug problems that may be occurring in deployed systems.
+
+In order to manage complexity in the juju agents, there are *workers* that have very distinct and limited purpose. Workers can have dependencies on other workers. The [dependency engine](https://godoc.org/gopkg.in/juju/worker.v1/dependency) is the entity that runs the workers and deals with those dependencies. The `juju_engine_report` is the current view into the dependency engine running the agent's workers.
+
+# Usage
+Can be run on any juju machine, expected state is different for controller machines, ha, and machines running workloads.
+```code
+juju_engine_report
+```
+## Example output
+```text
+manifolds:
+ agent:
+ inputs: []
+ report:
+ agent: machine-0
+ model-uuid: 1b13f1f5-c0cf-47c5-86ae-55c393e19405
+ resource-log: []
+ start-count: 1
+ started: 2018-08-09 22:01:39
+ state: started
+ api-address-updater:
+ inputs:
+ - agent
+ - api-caller
+ - migration-fortress
+ - migration-inactive-flag
+ report:
+ servers:
+ - - 10.173.141.131:17070
+ - 127.0.0.1:17070
+ - '[::1]:17070'
+ resource-log:
+ - name: migration-inactive-flag
+ type: '*engine.Flag'
+ - name: migration-fortress
+ type: '*fortress.Guest'
+ - name: agent
+ type: '*agent.Agent'
+ - name: api-caller
+ type: '*base.APICaller'
+ start-count: 1
+ started: 2018-08-09 22:01:41
+ state: started
+ api-caller:
+ inputs:
+ - agent
+ - api-config-watcher
+ resource-log:
+ - name: agent
+ type: '*agent.Agent'
+ start-count: 1
+ started: 2018-08-09 22:01:40
+ state: started
+# and many more
+```
+
+# Interesting Output
+
+* Dependencies with a larger `start_count` than others. This can indicate that the worker is bouncing.
+
+* Dependencies that are stopped when they should be started. Perhaps the `inputs` are not starting.
+
+* Dependencies that are started which should be stopped. Can prevent a unit from upgrading or migrating if the workers do not quiesce.
+
+* A controllers engine report will contain the model cache contents as of 2.9
+
+* The report from an individual unit contains the local-state and relation, formerly in a file on the unit:
+```
+ report:
+ local-state:
+ hook-kind: continue
+ hook-step: pending
+ installed: true
+ leader: true
+ removed: false
+ started: true
+ stopped: false
+ relations:
+ "0":
+ application-members:
+ ntp: 0
+ dying: false
+ endpoint: ntp-peers
+ is-peer: false
+ members: {}
+ relation: ntp:ntp-peers
+ "1":
+ application-members:
+ ubuntu: 0
+ dying: false
+ endpoint: juju-info
+ is-peer: false
+ members:
+ ubuntu/0: 0
+ relation: ntp:juju-info ubuntu:juju-info
+```
\ No newline at end of file
diff --git a/tmp/t/agent-introspection-juju_goroutines.md b/tmp/t/agent-introspection-juju_goroutines.md
new file mode 100644
index 000000000..44d9c5327
--- /dev/null
+++ b/tmp/t/agent-introspection-juju_goroutines.md
@@ -0,0 +1,128 @@
+(agent-introspection-juju_goroutines)=
+# Agent introspection: juju_goroutines
+
+> See also: {ref}`Agent introspection `
+
+The `juju_goroutines` function allows the operator to quickly get a list of running goroutines from the agent.
+
+When called without any argument the goroutines for the machine agent are returned.
+
+The output of this is mostly just useful for Juju developers to help identify where things may be stuck.
+
+```bash
+$ juju_goroutines
+Querying @jujud-machine-0 introspection socket: /debug/pprof/goroutine?debug=1
+goroutine profile: total 234
+19 @ 0x42f59a 0x42f64e 0x406c62 0x40691b 0x951ada 0x9c34ed 0x9c0177 0x45b211
+# 0x951ad9 gopkg.in/tomb%2ev1.(*Tomb).Wait+0x49 /home/tim/go/src/gopkg.in/tomb.v1/tomb.go:113
+# 0x9c34ec github.com/juju/juju/api/watcher.(*commonWatcher).Wait+0x2c /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:138
+# 0x9c0176 github.com/juju/juju/worker/catacomb.(*Catacomb).add.func1+0x86 /home/tim/go/src/github.com/juju/juju/worker/catacomb/catacomb.go:175
+
+19 @ 0x42f59a 0x42f64e 0x406c62 0x40691b 0x9599f9 0xa20249 0x9c6673 0x9c69e9 0x45b211
+# 0x9599f8 github.com/juju/juju/rpc.(*Conn).Call+0x128 /home/tim/go/src/github.com/juju/juju/rpc/client.go:148
+# 0xa20248 github.com/juju/juju/api.(*state).APICall+0x1c8 /home/tim/go/src/github.com/juju/juju/api/apiclient.go:917
+# 0x9c6672 github.com/juju/juju/api/watcher.makeWatcherAPICaller.func1+0x142 /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:54
+# 0x9c69e8 github.com/juju/juju/api/watcher.(*commonWatcher).commonLoop.func2+0xe8 /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:104
+
+19 @ 0x42f59a 0x42f64e 0x406c62 0x40691b 0x9c6732 0x45b211
+# 0x9c6731 github.com/juju/juju/api/watcher.(*commonWatcher).commonLoop.func1+0x71 /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:88
+
+19 @ 0x42f59a 0x42f64e 0x43ff34 0x43fb59 0x4646a2 0x9c3438 0x45b211
+# 0x43fb58 sync.runtime_Semacquire+0x38 /snap/go/2130/src/runtime/sema.go:56
+# 0x4646a1 sync.(*WaitGroup).Wait+0x71 /snap/go/2130/src/sync/waitgroup.go:129
+# 0x9c3437 github.com/juju/juju/api/watcher.(*commonWatcher).commonLoop+0xf7 /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:128
+
+19 @ 0x42f59a 0x43f2b0 0x9c02d8 0x45b211
+# 0x9c02d7 github.com/juju/juju/worker/catacomb.(*Catacomb).add.func2+0x107 /home/tim/go/src/github.com/juju/juju/worker/catacomb/catacomb.go:181
+
+15 @ 0x42f59a 0x43f2b0 0x9bffcd 0x45b211
+# 0x9bffcc github.com/juju/juju/worker/catacomb.Invoke.func2+0x14c /home/tim/go/src/github.com/juju/juju/worker/catacomb/catacomb.go:101
+
+13 @ 0x42f59a 0x42f64e 0x406c62 0x40691b 0xe5ee92 0xe60115 0x45b211
+# 0xe5ee91 github.com/juju/juju/worker/fortress.(*fortress).Visit+0x191 /home/tim/go/src/github.com/juju/juju/worker/fortress/fortress.go:63
+# 0xe60114 github.com/juju/juju/worker/fortress.Occupy.func2+0x44 /home/tim/go/src/github.com/juju/juju/worker/fortress/occupy.go:50
+
+11 @ 0x42f59a 0x42f64e 0x406c62 0x40695b 0x9c3813 0x9c6c73 0x45b211
+# 0x9c3812 github.com/juju/juju/api/watcher.(*notifyWatcher).loop+0x1c2 /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:180
+# 0x9c6c72 github.com/juju/juju/api/watcher.NewNotifyWatcher.func1+0x52 /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:160
+
+7 @ 0x42f59a 0x43f2b0 0x9c0e35 0x9c1aca 0x9bfdd5 0x9c00a1 0x45b211
+# 0x9c0e34 github.com/juju/juju/watcher.(*NotifyWorker).loop+0x154 /home/tim/go/src/github.com/juju/juju/watcher/notify.go:90
+# 0x9c1ac9 github.com/juju/juju/watcher.(*NotifyWorker).(github.com/juju/juju/watcher.loop)-fm+0x29 /home/tim/go/src/github.com/juju/juju/watcher/notify.go:71
+# 0x9bfdd4 github.com/juju/juju/worker/catacomb.runSafely+0x54 /home/tim/go/src/github.com/juju/juju/worker/catacomb/catacomb.go:289
+# 0x9c00a0 github.com/juju/juju/worker/catacomb.Invoke.func3+0x80 /home/tim/go/src/github.com/juju/juju/worker/catacomb/catacomb.go:116
+
+6 @ 0x42f59a 0x42f64e 0x406c62 0x40691b 0x951ada 0x9bf89d 0x9c11f1 0xe5e49f 0xe5bbd7 0x45b211
+# 0x951ad9 gopkg.in/tomb%2ev1.(*Tomb).Wait+0x49 /home/tim/go/src/gopkg.in/tomb.v1/tomb.go:113
+# 0x9bf89c github.com/juju/juju/worker/catacomb.(*Catacomb).Wait+0x2c /home/tim/go/src/github.com/juju/juju/worker/catacomb/catacomb.go:204
+# 0x9c11f0 github.com/juju/juju/watcher.(*NotifyWorker).Wait+0x30 /home/tim/go/src/github.com/juju/juju/watcher/notify.go:138
+# 0xe5e49e github.com/juju/juju/worker/dependency.(*Engine).runWorker.func2+0x4ce /home/tim/go/src/github.com/juju/juju/worker/dependency/engine.go:464
+# 0xe5bbd6 github.com/juju/juju/worker/dependency.(*Engine).runWorker+0x1c6 /home/tim/go/src/github.com/juju/juju/worker/dependency/engine.go:468
+
+6 @ 0x42f59a 0x42f64e 0x406c62 0x40691b 0x951ada 0x9bf89d 0x9c11f1 0xe600bb 0xe5f6e1 0x45b211
+# 0x951ad9 gopkg.in/tomb%2ev1.(*Tomb).Wait+0x49 /home/tim/go/src/gopkg.in/tomb.v1/tomb.go:113
+# 0x9bf89c github.com/juju/juju/worker/catacomb.(*Catacomb).Wait+0x2c /home/tim/go/src/github.com/juju/juju/worker/catacomb/catacomb.go:204
+# 0x9c11f0 github.com/juju/juju/watcher.(*NotifyWorker).Wait+0x30 /home/tim/go/src/github.com/juju/juju/watcher/notify.go:138
+# 0xe600ba github.com/juju/juju/worker/fortress.Occupy.func1+0xca /home/tim/go/src/github.com/juju/juju/worker/fortress/occupy.go:38
+# 0xe5f6e0 github.com/juju/juju/worker/fortress.guestTicket.complete+0x40 /home/tim/go/src/github.com/juju/juju/worker/fortress/fortress.go:151
+
+[extra bits snipped for brevity]
+```
+
+To call on a unit agent, the agent name as defined in `/var/lib/juju/agents/` should be specified as the second argument.
+
+```bash
+$ juju_goroutines unit-ubuntu-lite-2
+Querying @jujud-unit-ubuntu-lite-2 introspection socket: /debug/pprof/goroutine?debug=1
+goroutine profile: total 216
+19 @ 0x42f59a 0x43f2b0 0x9c02d8 0x45b211
+# 0x9c02d7 github.com/juju/juju/worker/catacomb.(*Catacomb).add.func2+0x107 /home/tim/go/src/github.com/juju/juju/worker/catacomb/catacomb.go:181
+
+17 @ 0x42f59a 0x42f64e 0x406c62 0x40691b 0x951ada 0x9c34ed 0x9c0177 0x45b211
+# 0x951ad9 gopkg.in/tomb%2ev1.(*Tomb).Wait+0x49 /home/tim/go/src/gopkg.in/tomb.v1/tomb.go:113
+# 0x9c34ec github.com/juju/juju/api/watcher.(*commonWatcher).Wait+0x2c /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:138
+# 0x9c0176 github.com/juju/juju/worker/catacomb.(*Catacomb).add.func1+0x86 /home/tim/go/src/github.com/juju/juju/worker/catacomb/catacomb.go:175
+
+17 @ 0x42f59a 0x42f64e 0x406c62 0x40691b 0x9599f9 0xa20249 0x9c6673 0x9c69e9 0x45b211
+# 0x9599f8 github.com/juju/juju/rpc.(*Conn).Call+0x128 /home/tim/go/src/github.com/juju/juju/rpc/client.go:148
+# 0xa20248 github.com/juju/juju/api.(*state).APICall+0x1c8 /home/tim/go/src/github.com/juju/juju/api/apiclient.go:917
+# 0x9c6672 github.com/juju/juju/api/watcher.makeWatcherAPICaller.func1+0x142 /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:54
+# 0x9c69e8 github.com/juju/juju/api/watcher.(*commonWatcher).commonLoop.func2+0xe8 /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:104
+
+17 @ 0x42f59a 0x42f64e 0x406c62 0x40691b 0x9c6732 0x45b211
+# 0x9c6731 github.com/juju/juju/api/watcher.(*commonWatcher).commonLoop.func1+0x71 /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:88
+
+17 @ 0x42f59a 0x42f64e 0x43ff34 0x43fb59 0x4646a2 0x9c3438 0x45b211
+# 0x43fb58 sync.runtime_Semacquire+0x38 /snap/go/2130/src/runtime/sema.go:56
+# 0x4646a1 sync.(*WaitGroup).Wait+0x71 /snap/go/2130/src/sync/waitgroup.go:129
+# 0x9c3437 github.com/juju/juju/api/watcher.(*commonWatcher).commonLoop+0xf7 /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:128
+
+13 @ 0x42f59a 0x42f64e 0x406c62 0x40695b 0x9c3813 0x9c6c73 0x45b211
+# 0x9c3812 github.com/juju/juju/api/watcher.(*notifyWatcher).loop+0x1c2 /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:180
+# 0x9c6c72 github.com/juju/juju/api/watcher.NewNotifyWatcher.func1+0x52 /home/tim/go/src/github.com/juju/juju/api/watcher/watcher.go:160
+
+11 @ 0x42f59a 0x42f64e 0x406c62 0x40691b 0xe5ee92 0xe60115 0x45b211
+# 0xe5ee91 github.com/juju/juju/worker/fortress.(*fortress).Visit+0x191 /home/tim/go/src/github.com/juju/juju/worker/fortress/fortress.go:63
+# 0xe60114 github.com/juju/juju/worker/fortress.Occupy.func2+0x44 /home/tim/go/src/github.com/juju/juju/worker/fortress/occupy.go:50
+
+10 @ 0x42f59a 0x42f64e 0x406c62 0x40695b 0xa2f2b8 0x45b211
+# 0xa2f2b7 gopkg.in/natefinch/lumberjack%2ev2.(*Logger).millRun+0x57 /home/tim/go/src/gopkg.in/natefinch/lumberjack.v2/lumberjack.go:379
+
+10 @ 0x42f59a 0x43f2b0 0x9bffcd 0x45b211
+# 0x9bffcc github.com/juju/juju/worker/catacomb.Invoke.func2+0x14c /home/tim/go/src/github.com/juju/juju/worker/catacomb/catacomb.go:101
+
+5 @ 0x42f59a 0x42f64e 0x406c62 0x40691b 0x951ada 0x9bf89d 0x9c11f1 0xe5e49f 0xe5bbd7 0x45b211
+# 0x951ad9 gopkg.in/tomb%2ev1.(*Tomb).Wait+0x49 /home/tim/go/src/gopkg.in/tomb.v1/tomb.go:113
+# 0x9bf89c github.com/juju/juju/worker/catacomb.(*Catacomb).Wait+0x2c /home/tim/go/src/github.com/juju/juju/worker/catacomb/catacomb.go:204
+# 0x9c11f0 github.com/juju/juju/watcher.(*NotifyWorker).Wait+0x30 /home/tim/go/src/github.com/juju/juju/watcher/notify.go:138
+# 0xe5e49e github.com/juju/juju/worker/dependency.(*Engine).runWorker.func2+0x4ce /home/tim/go/src/github.com/juju/juju/worker/dependency/engine.go:464
+# 0xe5bbd6 github.com/juju/juju/worker/dependency.(*Engine).runWorker+0x1c6 /home/tim/go/src/github.com/juju/juju/worker/dependency/engine.go:468
+
+5 @ 0x42f59a 0x42f64e 0x406c62 0x40691b 0x951ada 0x9bf89d 0x9c11f1 0xe600bb 0xe5f6e1 0x45b211
+# 0x951ad9 gopkg.in/tomb%2ev1.(*Tomb).Wait+0x49 /home/tim/go/src/gopkg.in/tomb.v1/tomb.go:113
+# 0x9bf89c github.com/juju/juju/worker/catacomb.(*Catacomb).Wait+0x2c /home/tim/go/src/github.com/juju/juju/worker/catacomb/catacomb.go:204
+# 0x9c11f0 github.com/juju/juju/watcher.(*NotifyWorker).Wait+0x30 /home/tim/go/src/github.com/juju/juju/watcher/notify.go:138
+# 0xe600ba github.com/juju/juju/worker/fortress.Occupy.func1+0xca /home/tim/go/src/github.com/juju/juju/worker/fortress/occupy.go:38
+# 0xe5f6e0 github.com/juju/juju/worker/fortress.guestTicket.complete+0x40 /home/tim/go/src/github.com/juju/juju/worker/fortress/fortress.go:151
+[extra bits snipped for brevity]
+```
\ No newline at end of file
diff --git a/tmp/t/agent-introspection-juju_heap_profile.md b/tmp/t/agent-introspection-juju_heap_profile.md
new file mode 100644
index 000000000..59db79982
--- /dev/null
+++ b/tmp/t/agent-introspection-juju_heap_profile.md
@@ -0,0 +1,51 @@
+(agent-introspection-juju_heap_profile)=
+# Agent introspection: juju_heap_profile
+
+> See also: {ref}`Agent introspection `
+
+The heap profile provides memory allocation samples. Helpful to monitor current memory usage and find memory leaks. This is primarily useful to developers to help debug problems that may be occurring in deployed systems.
+
+
+
+# Usage
+Can be run on any juju machine. Suggest putting the output in a file, so it can be compared at different points in time.
+```code
+juju_heap_profile > heap_profile.01
+```
+## Example output
+```text
+heap profile: 31: 694464 [33638: 106713992] @ heap/1048576
+1: 196608 [1: 196608] @ 0x2d3fa53 0x2d3f9f6 0x2d40545 0x2d4030f 0x2d05ddb 0x2d0479f 0x2d05bf1 0x2d26c32 0x8a3cef 0x2d0381d 0x2d04146 0x2d008ba 0x2d01fbe 0x8a779b 0x8a2797 0x468fc1
+# 0x2d3fa52 github.com/juju/juju/core/logger.NewBufferedLogger+0x192 /home/heather/work-test/src/github.com/juju/juju/core/logger/buf.go:43
+# 0x2d3f9f5 github.com/juju/juju/apiserver.(*apiServerLoggers).getLogger+0x135 /home/heather/work-test/src/github.com/juju/juju/apiserver/logsink.go:66
+# 0x2d40544 github.com/juju/juju/apiserver.(*agentLoggingStrategy).init+0x1c4 /home/heather/work-test/src/github.com/juju/juju/apiserver/logsink.go:175
+# 0x2d4030e github.com/juju/juju/apiserver.newAgentLogWriteCloserFunc.func1+0xae /home/heather/work-test/src/github.com/juju/juju/apiserver/logsink.go:147
+# 0x2d05dda github.com/juju/juju/apiserver/logsink.(*logSinkHandler).ServeHTTP.func1+0x19a /home/heather/work-test/src/github.com/juju/juju/apiserver/logsink/logsink.go:196
+# 0x2d0479e github.com/juju/juju/apiserver/websocket.Serve+0xde /home/heather/work-test/src/github.com/juju/juju/apiserver/websocket/websocket.go:55
+# 0x2d05bf0 github.com/juju/juju/apiserver/logsink.(*logSinkHandler).ServeHTTP+0xb0 /home/heather/work-test/src/github.com/juju/juju/apiserver/logsink/logsink.go:270
+# 0x2d26c31 github.com/juju/juju/apiserver.(*Server).trackRequests.func1+0x111 /home/heather/work-test/src/github.com/juju/juju/apiserver/apiserver.go:1015
+# 0x8a3cee net/http.HandlerFunc.ServeHTTP+0x2e /snap/go/9605/src/net/http/server.go:2084
+# 0x2d0381c github.com/juju/juju/apiserver/httpcontext.(*BasicAuthHandler).ServeHTTP+0x3fc /home/heather/work-test/src/github.com/juju/juju/apiserver/httpcontext/auth.go:168
+# 0x2d04145 github.com/juju/juju/apiserver/httpcontext.(*QueryModelHandler).ServeHTTP+0x325 /home/heather/work-test/src/github.com/juju/juju/apiserver/httpcontext/model.go:52
+# 0x2d008b9 github.com/bmizerany/pat.(*PatternServeMux).ServeHTTP+0x199 /home/heather/work-test/pkg/mod/github.com/bmizerany/pat@v0.0.0-20160217103242-c068ca2f0aac/mux.go:117
+# 0x2d01fbd github.com/juju/juju/apiserver/apiserverhttp.(*Mux).ServeHTTP+0x9d /home/heather/work-test/src/github.com/juju/juju/apiserver/apiserverhttp/mux.go:67
+# 0x8a779a net/http.serverHandler.ServeHTTP+0x43a /snap/go/9605/src/net/http/server.go:2916
+# 0x8a2796 net/http.(*conn).serve+0x5d6 /snap/go/9605/src/net/http/server.go:1966
+
+1: 196608 [1: 196608] @ 0x2ffcec5 0x2ffce0e 0x2ffd07c 0x778495 0x468fc1
+# 0x2ffcec4 github.com/juju/juju/core/logger.NewBufferedLogger+0x264 /home/heather/work-test/src/github.com/juju/juju/core/logger/buf.go:43
+# 0x2ffce0d github.com/juju/juju/worker/modelworkermanager.newModelLogger+0x1ad /home/heather/work-test/src/github.com/juju/juju/worker/modelworkermanager/recordlogger.go:28
+# 0x2ffd07b github.com/juju/juju/worker/modelworkermanager.(*modelWorkerManager).starter.func1+0x41b /home/heather/work-test/src/github.com/juju/juju/worker/modelworkermanager/modelworkermanager.go:261
+# 0x778494 github.com/juju/worker/v3.(*Runner).runWorker+0x2d4 /home/heather/work-test/pkg/mod/github.com/juju/worker/v3@v3.0.0-20220204100750-e23db69a42d2/runner.go:580
+
+# and many more
+```
+
+# Interesting Output
+The output of the heap profile can be difficult to read on its own. Using the pprof go tool can help.
+
+To find a memory leak, compare 2 heap profiles:
+```text
+go tool pprof -http localhost:8100 -base juju_heap_profile-2022-06-11.00 jujud-2.9.29/jujud juju_heap_profile-2022-06-12.16
+```
+Find jujud binaries in the [streams](https://streams.canonical.com/juju/tools/agent/)
\ No newline at end of file
diff --git a/tmp/t/agent-introspection-juju_machine_lock.md b/tmp/t/agent-introspection-juju_machine_lock.md
new file mode 100644
index 000000000..923050629
--- /dev/null
+++ b/tmp/t/agent-introspection-juju_machine_lock.md
@@ -0,0 +1,68 @@
+(agent-introspection-juju_machine_lock)=
+# Agent introspection: juju_machine_lock
+
+> See also: {ref}`Agent introspection `, {ref}`Logfile: /var/log/juju/machine-lock.log `
+
+The `juju_machine_lock` introspection function was introduced in 2.3.9 and 2.4.2.
+
+This function actually calls into every agent on the machine to ask about the agent's view of the hook execution lock. Where the {ref}`machine-lock.log ` file shows the history of the machine lock, the introspection endpoint shows the current status of the lock, whether the agent holds the lock, or is waiting for the lock.
+
+During a deploy of `hadoop-kafka`, after the machine 0 has started, and is deploying the two units, we can see the following:
+
+```
+machine-0:
+ holder: none
+unit-namenode-0:
+ holder: uniter (run install hook), holding 1m42s
+unit-resourcemanager-0:
+ holder: none
+ waiting:
+ - uniter (run install hook), waiting 1m41s
+```
+You can see that the `namenode/0` unit has the uniter worker holding the hook, and it is running the install hook, and at the time of executing the `juju_machine_lock` command it had been holding the lock for one minute and 42 seconds.
+
+You can additionally see that the `resourcemanager/0` unit is waiting to run its install hook.
+
+As the installation progresses, the subordinate units are deployed, and the output looks more like this:
+
+```
+machine-0:
+ holder: none
+unit-ganglia-node-7:
+ holder: none
+ waiting:
+ - uniter (run install hook), waiting 1s
+unit-ganglia-node-8:
+ holder: none
+unit-namenode-0:
+ holder: uniter (run relation-joined (2; slave/0) hook), holding 1s
+unit-resourcemanager-0:
+ holder: none
+ waiting:
+ - uniter (run relation-joined (1; namenode/0) hook), waiting 1s
+unit-rsyslog-forwarder-ha-7:
+ holder: none
+ waiting:
+ - uniter (run install hook), waiting 1s
+unit-rsyslog-forwarder-ha-8:
+ holder: none
+```
+
+When everything is idle, the output looks like this:
+
+```
+machine-0:
+ holder: none
+unit-ganglia-node-7:
+ holder: none
+unit-ganglia-node-8:
+ holder: none
+unit-namenode-0:
+ holder: none
+unit-resourcemanager-0:
+ holder: none
+unit-rsyslog-forwarder-ha-7:
+ holder: none
+unit-rsyslog-forwarder-ha-8:
+ holder: none
+```
\ No newline at end of file
diff --git a/tmp/t/agent-introspection-juju_metrics.md b/tmp/t/agent-introspection-juju_metrics.md
new file mode 100644
index 000000000..45c1f8df5
--- /dev/null
+++ b/tmp/t/agent-introspection-juju_metrics.md
@@ -0,0 +1,45 @@
+(agent-introspection-juju_metrics)=
+# Agent introspection: juju_metrics
+
+> See also: {ref}`Agent introspection `
+
+The juju metrics introspection tool provides the current values of metrics which juju tracking. Some of these are more interesting over time using a tool such as grafana. More information can be found in [Monitoring Juju Controllers](https://discourse.charmhub.io/t/monitoring-juju-controllers/430/5).
+
+This is primarily useful to developers to help debug problems that may be occurring in deployed systems. Advance admins can use the data to see when investigation is required, or an error is hidden.
+
+# Usage
+
+Can be run on any juju machine.
+
+```code
+juju_metrics
+```
+## Example output
+```text
+# HELP go_gc_duration_seconds A summary of the pause duration of garbage collection cycles.
+# TYPE go_gc_duration_seconds summary
+go_gc_duration_seconds{quantile="0"} 4.6921e-05
+go_gc_duration_seconds{quantile="0.25"} 8.3083e-05
+go_gc_duration_seconds{quantile="0.5"} 9.8263e-05
+go_gc_duration_seconds{quantile="0.75"} 0.00013904
+go_gc_duration_seconds{quantile="1"} 0.000921937
+go_gc_duration_seconds_sum 0.201048689
+go_gc_duration_seconds_count 1521
+# HELP go_goroutines Number of goroutines that currently exist.
+# TYPE go_goroutines gauge
+go_goroutines 704
+# HELP go_info Information about the Go environment.
+# TYPE go_info gauge
+go_info{version="go1.18.1"} 1
+# HELP go_memstats_alloc_bytes Number of bytes allocated and still in use.
+# TYPE go_memstats_alloc_bytes gauge
+go_memstats_alloc_bytes 2.3154496e+07
+# and many more
+```
+# Interesting Output
+
+* `process_open_fds`: how many file descriptors are open. This should not grow over time in a stable juju deployment.
+
+* `juju_dependency_engine_worker_start`: how many times a dependency has started. Each dependency has an individual number. None should have a number significantly higher than the rest. This indicates the worker is restarting due to an error. Also seen in the [juju_engine_report](https://discourse.jujucharms.com/t/agent-introspection-juju-engine-report/146).
+
+* `go_goroutines`: a gauge for the current number of goroutines. Should not be growing in a stable config.
\ No newline at end of file
diff --git a/tmp/t/agent-introspection-juju_start_unit.md b/tmp/t/agent-introspection-juju_start_unit.md
new file mode 100644
index 000000000..3445307ce
--- /dev/null
+++ b/tmp/t/agent-introspection-juju_start_unit.md
@@ -0,0 +1,13 @@
+(agent-introspection-juju_start_unit)=
+# Agent introspection: juju_start_unit
+
+> See also: {ref}`Agent introspection `
+
+The `juju_start_unit` introspection function was introduced in 2.9.
+
+In 2.9 the machine and unit agents were combined into a single process running on juju deployed machines. This tools allows you to see the start a stopped unit agent running inside of that single process. It takes a unit name as input. Example output:
+
+```
+$ juju_start_unit neutron-openvswitch/0
+neutron-openvswitch/0: started
+```
\ No newline at end of file
diff --git a/tmp/t/agent-introspection-juju_stop_unit.md b/tmp/t/agent-introspection-juju_stop_unit.md
new file mode 100644
index 000000000..b3570cc0b
--- /dev/null
+++ b/tmp/t/agent-introspection-juju_stop_unit.md
@@ -0,0 +1,19 @@
+(agent-introspection-juju_stop_unit)=
+# Agent introspection: juju_stop_unit
+
+> See also: {ref}`Agent introspection `
+
+```{caution}
+
+**For Kubernetes charms:**
This is not currently supported. (In the future it may be supported through Pebble.)
+
+```
+
+The `juju_stop_unit` introspection function was introduced in 2.9.
+
+In 2.9 the machine and unit agents were combined into a single process running on juju deployed machines. This tools allows you to stop a unit agent running inside of that single process. It takes a unit name as input. Example output:
+
+```
+$ juju_stop_unit neutron-openvswitch/0
+neutron-openvswitch/0: stopped
+```
\ No newline at end of file
diff --git a/tmp/t/agent-introspection-juju_unit_status.md b/tmp/t/agent-introspection-juju_unit_status.md
new file mode 100644
index 000000000..07a3b27bf
--- /dev/null
+++ b/tmp/t/agent-introspection-juju_unit_status.md
@@ -0,0 +1,16 @@
+(agent-introspection-juju_unit_status)=
+# Agent introspection: juju_unit_status
+
+> See also: {ref}`Agent introspection `
+
+The `juju_unit_status` introspection function was introduced in 2.9.
+
+In 2.9 the machine and unit agents were combined into a single process running on juju deployed machines. This tools allows you to see the status of agents running inside of that single process. Example output:
+
+```
+agent: machine-6
+units:
+ lxd/0: running
+ neutron-openvswitch/0: running
+ nova-compute/0: running
+```
\ No newline at end of file
diff --git a/tmp/t/agent-introspection.md b/tmp/t/agent-introspection.md
new file mode 100644
index 000000000..898915992
--- /dev/null
+++ b/tmp/t/agent-introspection.md
@@ -0,0 +1,27 @@
+(agent-introspection)=
+# Agent introspection
+
+Sometimes software doesn't do what you'd expect. Each of the {ref}`agents <117md>` that Juju runs has an internal worker for responding to introspection requests.
+
+As the agents start up, a goroutine is started to listen on an abstract domain socket. The listener talks HTTP, and has a number of registered endpoints. The initial work was to expose the internal golang runtime debugging endpoints for getting access to the running goroutines, CPU profiles, and memory heap profiles. This was then extended to add additional endpoints for much more Juju specific information.
+
+The Juju machine agent writes out a file to `/etc/profile.d/juju-introspection.sh` that defines a number of functions to easily get information out of the agent. These function names changed in Juju 2.3.9 and 2.4.2 to use underscores instead of dashes.
+
+- `juju_agent`
+- `juju_agent_call`
+- `juju_application_agent_name`
+- `juju_controller_agent_name`
+- `juju_cpu_profile`
+- {ref}``juju_engine_report` `
+- {ref}``juju_goroutines` `
+- {ref}``juju_heap_profile` `
+- `juju_machine_agent_name`
+- {ref}``juju_machine_lock` ` (since 2.3.9, 2.4.2)
+- {ref}``juju_metrics` `
+- `juju_pubsub_report` (since 2.3)
+- `juju_presence_report` (since 2.4)
+- {ref}``juju_start_unit` ` (since 2.9)
+- `juju_statepool_report`
+- `juju_statetracker_report`
+- {ref}``juju_stop_unit` ` (since 2.9)
+- {ref}``juju_unit_status` ` (since 2.9)
\ No newline at end of file
diff --git a/tmp/t/agent.md b/tmp/t/agent.md
new file mode 100644
index 000000000..724610b82
--- /dev/null
+++ b/tmp/t/agent.md
@@ -0,0 +1,116 @@
+(agent)=
+# Agent
+
+In Juju, an **agent** is a {ref}``jujud` ` / {ref}``containeragent` ` process that works to realise the state declared by a Juju end-user with a Juju client (e.g., {ref}`the Juju CLI `) for a Juju entity (e.g., controller, model, machine, unit) via {ref}`workers `.
+
+On machines, an agent is managed by `systemd`.
+
+> See more: [Juju Dev | Agent](https://juju.is/docs/dev/agent)
+
+**Contents:**
+
+- [Controller agent](#heading--controller-agent)
+- [Machine agent](#heading--machine-agent)
+- [Model agent](#heading--model-agent)
+- [Unit agent](#heading--unit-agent)
+
+Controller agent
+
+On machine and Kubernetes clouds, a `jujud` process running workers responsible for a {ref}`controller `. This includes, among others, the `apiserver` worker, which is responsible for running the Juju API server.
+
+
+Machine agent
+
+On machine clouds, a `jujud` process running workers responsible for a {ref}`machine `.
+
+Model agent
+
+On machine and Kubernetes clouds, a `jujud` process running workers responsible for all the {ref}`models ` associated with a given controller.
+
+
+Unit agent
+
+On machine / Kubernetes clouds, a `jujud` / `containeragent` process responsible for a {ref}`unit `.
+
+When a Juju user uses the client (e.g., types a command in the CLI), this goes to the controller agent's apiserver, which passes it on to the database. The database runs a background process that checks if anything has changed and, if so, emits an event (think "I've seen something that's changed. Do you care about it?"). The event cascades through Juju. The unit agent becomes aware of it by always polling the controller agent as part of a reconciliation loop trying to reconcile the unit agent's local state to the remote state on the controller (i.e., the state in the controller's database).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/tmp/t/application.md b/tmp/t/application.md
new file mode 100644
index 000000000..25f32d72b
--- /dev/null
+++ b/tmp/t/application.md
@@ -0,0 +1,107 @@
+(application)=
+# Application
+
+> See also: {ref}`How to manage applications `
+
+
+In Juju, an **application** is a running abstraction of a {ref}`charm ` in the Juju model. It is whatever software is defined by the charm. This could correspond to a traditional software package but it could also be less or more.
+
+An application is always hosted within a {ref}`model ` and consists of one or more {ref}`units `.
+
+
+An application can have {ref}`resources `, a {ref}`configuration <5471md>`, the ability to form {ref}`relations (integrations) `, and {ref}`actions `.
+
+
\ No newline at end of file
diff --git a/tmp/t/base.md b/tmp/t/base.md
new file mode 100644
index 000000000..e83a66b03
--- /dev/null
+++ b/tmp/t/base.md
@@ -0,0 +1,10 @@
+(base)=
+# Base
+
+> Starting with Juju 3.1, a 'base' replaces the older notion of 'series'.
+
+In Juju, a **base** is a way to identify a particular operating system (OS) image for a Juju {ref}`machine `.
+
+This can be done via the name of the OS followed by the `@` symbol and the channel of the OS that you want to target, specified in terms of `
+
{{ project }} ++ +
+
+
+
+