Improved getting started page (#724)

* Improved getting started page

Signed-off-by: Joe Elliott <[email protected]>

* Improved getting started

Signed-off-by: Joe Elliott <[email protected]>

* sprucing

Signed-off-by: Joe Elliott <[email protected]>

* cleaned up getting started png

Signed-off-by: Joe Elliott <[email protected]>

* improvements. removed trace image

Signed-off-by: Joe Elliott <[email protected]>

docs/tempo/website/getting-started/_index.md

@@ -6,30 +6,29 @@ weight: 100
 # Getting started with Tempo
 
 Distributed tracing visualizes the lifecycle of a request as it passes through
-an application. There are a few components that must be configured in order to get a
+a set of applications. There are a few components that must be configured in order to get a
 working distributed tracing visualization.
 
-## 1. Client instrumentation
+This document discusses the four major pieces necessary to build out a tracing system: 
+Instrumentation, Pipeline, Backend and Visualization. If one were to build a diagram laying 
+out these pieces it may look something like this:
 
-#### OpenTelemetry Instrumentation SDKs
+<p align="center"><img src="getting-started.png" alt="Tracing Overview"></p>
+
+## 1. Instrumentation
+
+#### Instrumentation SDKs
 
 The first building block to a functioning distributed tracing visualization pipeline
-is client instrumentation, which is the process of adding instrumentation points in the application that collects telemetry information. 
-
-SDKs that are available in the most commonly used programming languages are listed below -
-
-* [OpenTemeletry CPP](https://github.com/open-telemetry/opentelemetry-cpp)
-* [OpenTemeletry Java](https://github.com/open-telemetry/opentelemetry-java)
-* [OpenTemeletry JS](https://github.com/open-telemetry/opentelemetry-js)
-* [OpenTemeletry .NET](https://github.com/open-telemetry/opentelemetry-dotnet)
-* [OpenTemeletry Lambda](https://github.com/open-telemetry/opentelemetry-lambda)
-* [OpenTemeletry Go](https://github.com/open-telemetry/opentelemetry-go)
-* [OpenTemeletry Python](https://github.com/open-telemetry/opentelemetry-python)
-* [OpenTemeletry Ruby](https://github.com/open-telemetry/opentelemetry-ruby)
-* [OpenTemeletry Swift](https://github.com/open-telemetry/opentelemetry-swift)
-* [OpenTemeletry Ruby](https://github.com/open-telemetry/opentelemetry-ruby)
-* [OpenTemeletry PHP](https://github.com/open-telemetry/opentelemetry-php)
-* [OpenTemeletry Rust](https://github.com/open-telemetry/opentelemetry-rust)
+is client instrumentation, which is the process of adding instrumentation points in the application that 
+creates and offloads spans. 
+
+Below is a list of the most popular frameworks used for client instrumentation. Each of these have SDKs 
+in most commonly used programming languages and you should pick one according to your application needs.
+
+* [OpenTracing/Jaeger](https://www.jaegertracing.io/docs/latest/client-libraries/)
+* [Zipkin](https://zipkin.io/pages/tracers_instrumentation)
+* [OpenTemeletry](https://opentelemetry.io/docs/concepts/instrumenting/)
 
 #### OpenTelemetry Auto Instrumentation
 
@@ -40,29 +39,32 @@ information from a client application with minimal manual instrumentation of the
 * [OpenTemeletry .NET Autoinstrumentation](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation)
 * [OpenTemeletry Python Autoinstrumentation](https://github.com/open-telemetry/opentelemetry-python-contrib)
 
-> Note: Check out our [instrumentation examples]() to learn how to instrument your
+> Note: Check out our [instrumentation examples]({{< relref "../guides/instrumentation" >}}) to learn how to instrument your
 > favourite language for distributed tracing.
 
-## 2. Grafana Agent
+## 2. Pipeline (Grafana Agent)
 
 Once your application is instrumented for tracing, the next step is to send these traces
-to a backend for storage and visualization. The Grafana Agent is a service that is
-deployed close to the application, either on the same node or within the same cluster
-(in kubernetes) to quickly offload traces from the application and forward them to a storage
-backend. It also abstracts features like trace batching and backend routing
-away from the client. 
+to a backend for storage and visualization. It is common to build a tracing pipeline that 
+offloads spans from your application, buffers them and eventually forwards them to a backend. Tracing
+pipelines are optional (most clients can send directly to Tempo), but you will find that
+they become more critical the larger and more robust your tracing system is.
+
+The Grafana Agent is a service that is deployed close to the application, either on the same node or 
+within the same cluster (in kubernetes) to quickly offload traces from the application and forward them to 
+a storage backend. It also abstracts features like trace batching and backend routing away from the client. 
 
 To learn more about the Grafana Agent and how to set it up for tracing with Tempo,
 refer to [this blog post](https://grafana.com/blog/2020/11/17/tracing-with-the-grafana-agent-and-grafana-tempo/).
 
-> **Note**: OpenTelemetry Collector / Jaeger Agent can also be used at the agent layer.
+> **Note**: The [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector) / [Jaeger Agent](https://www.jaegertracing.io/docs/latest/deployment/) can also be used at the agent layer.
 > Refer to [this blog post](https://grafana.com/blog/2021/04/13/how-to-send-traces-to-grafana-clouds-tempo-service-with-opentelemetry-collector/)
 > to see how the OpenTelemetry Collector can be used with Grafana Cloud Tempo.
 
+## 3. Backend (Tempo)
 
-## 3. Setting up Tempo Backend
-
-Grafana Tempo is an easy-to-use and high-scale distributed tracing backend used to store and query traces.
+Grafana Tempo is an easy-to-use and high-scale distributed tracing backend used to store and query traces. The purpose of 
+the tracing backend is to store and retrieve traces on demand.
 
 Getting started with Tempo is easy.
 
@@ -73,9 +75,9 @@ Getting started with Tempo is easy.
 > **Note:** The Grafana Agent is already set up to use Tempo. Refer to the [configuration](https://github.com/grafana/agent/blob/main/docs/configuration-reference.md#tempo_config) and [example](https://github.com/grafana/agent/blob/main/example/docker-compose/agent/config/agent.yaml) for details.
 
 
-## 4. Visualization with Grafana
+## 4. Visualization (Grafana)
 
 Grafana has a built in Tempo datasource that can be used to query Tempo and visualize traces.
 For more information refer to the [Tempo data source](https://grafana.com/docs/grafana/latest/datasources/tempo/) topic.
 
-For Grafana configuration
+See [here]({{< relref "../configuration/querying" >}}) for details about Grafana configuration.

docs/tempo/website/getting-started/example-demo-app.md

@@ -1,11 +1,12 @@
 ---
-title: Examples with demo app
+title: Ready to go Examples
 ---
 
-# Examples with demo app
+# Examples
 
-If you don't have an application to instrument at the moment, then refer to the [examples](https://github.com/grafana/tempo/tree/main/example) 
-which show various deployment and [configuration]({{< relref "../configuration" >}}) options.
+These examples show various deployment and [configuration]({{< relref "../configuration" >}}) options. They include trace
+generators so an existing application is not necessary to get started experimenting with Tempo. If you are interested in
+instrumentation please check out these [examples]({{< relref "../guides/instrumentation" >}}).
 
 The linked folders contain example deployments of Tempo.  They are a good resource for getting some basic configurations together.
 
@@ -14,22 +15,22 @@ The linked folders contain example deployments of Tempo.  They are a good resour
 The [docker-compose](https://github.com/grafana/tempo/tree/main/example/docker-compose) examples are simpler and designed to show minimal configuration.  This is a great place
 to get started with Tempo and learn about various trace discovery flows.
 
-- [local storage](https://github.com/grafana/tempo/tree/main/example/docker-compose/readme.md#local-storage)
-- At its simplest, Tempo only requires a few parameters that identify where to store traces.
-- [s3/minio storage](https://github.com/grafana/tempo/tree/main/example/docker-compose/readme.md#s3)
-  - To reduce complexity not all config options are exposed on the command line.  This example uses the minio/s3 backend with a config file.
 - [Trace discovery with Loki](https://github.com/grafana/tempo/tree/main/example/docker-compose/readme.md#loki-derived-fields)
   - This example brings in Loki and shows how to use a log flow to discover traces.
-
+- [Local storage](https://github.com/grafana/tempo/tree/main/example/docker-compose/readme.md#local-storage)
+  - At its simplest, Tempo only requires a few parameters that identify where to store traces.
+- [S3/Minio storage](https://github.com/grafana/tempo/tree/main/example/docker-compose/readme.md#s3)
+  - To reduce complexity not all config options are exposed on the command line.  This example uses the minio/s3 backend with a config file.
 
 ## Tanka
 
-The Jsonnet based [example](https://github.com/grafana/tempo/tree/main/example/tk) shows a complete microservice based deployment.
+The Jsonnet based [example](https://github.com/grafana/tempo/tree/main/example/tk) shows a complete microservice based deployment. 
+There are single binary and microservices examples.
+
+## Helm
 
-- [single binary](https://github.com/grafana/tempo/tree/main/example/tk/readme.md#single-binary)
-  - A single binary jsonnet deployment.  Valuable for getting started with advanced configuration.
-- [microservices](https://github.com/grafana/tempo/tree/main/example/tk/readme.md#microservices)
-  - Tempo as a set of independently scalable microservices.  This is recommended for high volume full production deployments.
+The Helm [example](https://github.com/grafana/tempo/tree/main/example/helm) shows a complete microservice based deployment. 
+There are single binary and microservices examples.
 
 ## The New Stack (TNS) Demo