Improve docs (#35)

* wip: docs rewrite

* wip: improve links and descriptions

* chore: add more descriptions, fix formatting and delete unnecessary comments

ReadMe.md

@@ -1,15 +1,42 @@
 # Meerkat
+
 Observability Starter Kit for JVM Applications
 
 ## Introduction
 
-This project, initiated within the DevOps OSS space at SoftwareMill, aims to provide a ready-to-deploy configuration based 
-on OpenTelemetry for JVM applications. By providing a ready-to-deploy solution, we want to accelerate adding industry-standard observability practices into JVM applications.
-The Observability Starter Kit is designed to be easily implemented and extended to meet specific observability needs.
+This project, initiated within the DevOps OSS space at SoftwareMill, aims to provide a ready-to-deploy configuration based on OpenTelemetry for JVM applications. 
+
+It's made of two parts - [Kustomize](https://kustomize.io/#overview) manifests for Kubernetes and quick start configuration described with [Pulumi](https://www.pulumi.com/docs/languages-sdks/javascript/). If you already have a Kubernetes cluster, look into [deploying OpenTelemetry Operator configuration only](docs/Kustomize.md). If you want a demo, look into [try-me environment instructions](docs/TryMe.md), where you will find ready-to-deploy configuration of backends such as Loki, Grafana, Tempo and Mimir (known also as LGTM stack).
 
 **This starter kit is intended for Developers and DevOps professionals who wish to implement observability into their JVM-based applications using Kubernetes.
 Future plans include extending the configuration to additional platforms beyond Kubernetes, such as AWS ECS.**
 
+## Q&A
+
+- What does this project do?
+
+Meerkat is an observability bootstrapping aid for your JVM-based project. It deploys data backends for logs, traces, and metrics, along with Grafana dashboards and OpenTelemetry Operator, which is a glue to combine it all together.
+
+- What is OpenTelemetry?
+
+OpenTelemetry is an open-source Cloud Native Computing Foundation (CNCF) incubation project.
+OpenTelemetry facilitates the collection and processing of telemetry data (logs, metrics, traces) in a standardized way. 
+
+It's a de facto standard for telemetry data that is being supported by all major observability products and their communities. We're using OpenTelemetry Operator to simplify Collector creation and autoinstrumentation configuration.
+
+- What is an OpenTelemetry Collector?
+
+A Collector in OpenTelemetry ecosystem is an application that serves as a receiver, processor, and an exporter of telemetry data. If you're familiar with any other observability tool, you can appreciate the simplicity of this setup. 
+
+- How does autoinstrumentation work?
+
+In layman terms, we're detecting libraries used by an observed application to determine how to extract telemetry data from it. This doesn't require any kind of code modifying, because it relies on injecting a Java Agent as a sidecar to the application. However, based on the language and framework the application uses, not all data will be available by autoinstrumenting. More details [here](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md).
+
+## Getting started
+
+- [Quick start](docs/TryMe.md)
+- [Components overview](docs/Components.md)
+- [Kustomize](docs/Kustomize.md)
 
 ## Project Goals
 
@@ -20,20 +47,12 @@ We focus on:
 
 ## Why Observability and OpenTelemetry?
 
-In today's complex software environments, observability plays a crucial role. 
-It allows developers not only to see what is happening inside their applications but also to identify bottlenecks, 
-optimize processes, and quickly analyze and resolve issues. 
-
-OpenTelemetry is an open-source Cloud Native Computing Foundation (CNCF) incubation project.
-OpenTelemetry facilitates the collection and processing of telemetry data (logs, metrics, traces) in a standardized way. 
+In today's complex software environments, observability plays a crucial role.
+It allows developers not only to see what is happening inside their applications but also to identify bottlenecks,
+optimize processes, and quickly analyze and resolve issues.
 
 **We focus on OpenTelemetry because it standardizes software telemetry data. OpenTelemetry offers universal way to collect, process and send telemetry data to multiple vendors.**
 
-## Getting started
-
-- [Components Overview](docs/Components.md)
-- [Try me environment](docs/TryMe.md)
-
 ## What will be included?
 
 - Configuration files for OpenTelemetry Collector to be used together with OpenTelemetry Operator.

docs/Components.md

@@ -13,4 +13,4 @@ TODO: add explanation of why this or not other component
 - [Grafana Loki](https://grafana.com/oss/loki/)
 - [Grafana Mimir](https://grafana.com/oss/mimir/)
 - [Grafana Tempo](https://grafana.com/oss/tempo/)
-- [Prometheus]()
+- [Prometheus](https://prometheus.io/)

docs/Kustomize.md

@@ -0,0 +1,29 @@
+# Kustomize installation
+
+If you have a Kubernetes cluster already, you can only install our configuration with [Kustomize](https://kustomize.io/#overview) and [Helm](https://helm.sh/). Apart from your application already deployed, you will need to [deploy OpenTelemetry Operator](https://opentelemetry.io/docs/kubernetes/operator/) and [cert-manager](https://cert-manager.io/).
+
+To install cert-manager run:
+
+``` bash
+  helm repo add jetstack \ 
+  https://charts.jetstack.io --force-update 
+```
+
+and
+
+``` bash
+helm install \ 
+  cert-manager jetstack/cert-manager \
+  --namespace cert-manager \
+  --create-namespace \
+  --version v1.15.0 \
+  --set crds.enabled=true
+```
+
+Install operator:
+
+``` bash
+kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml
+```
+
+Once the Operator is up and running, proceed to install our Kustomize configuration by executing `kubectl apply -k .` in the root directory of this repo. This will install autoinstrumentation, roles, cluster roles, role bindings, service account, and Grafana dashboards (as configmaps).

docs/TryMe.md

@@ -1,14 +1,16 @@
 # Try-Me Local Environment Setup
 
 ## Overview
+
 The `try-me` directory offers scripts and configurations for setting up a local Kubernetes environment using 
 [Kind](https://kind.sigs.k8s.io/) and [Pulumi](https://www.pulumi.com/docs/languages-sdks/javascript/),
 making testing and development purposes of observability - friendly.
 
 ## Prerequisites
 
-- Docker installed - standalone Docker or Docker Desktop both work well
-- Pulumi CLI installed
+- [Docker](https://docs.docker.com/get-docker/) installed - standalone Docker or Docker Desktop both work well
+- [Pulumi CLI](https://www.pulumi.com/docs/install/)
+- [Node.js and npm](https://nodejs.org/en/download/package-manager)
 
 ## Running
 
@@ -17,16 +19,17 @@ making testing and development purposes of observability - friendly.
 First you need to run Kubernetes cluster on your localhost. For that we're running Kind cluster
 
 - **Configurations**: Adjust your setup by modifying the `kind-config.yml`.
-- **Scripts**: 
+- **Scripts**:
 Utilize
 
-```bash 
+```bash
 pushd ../try-me/kind
 
 ./cluster_create.sh
 
 popd
-``` 
+```
+
 to set up your Kubernetes cluster and
 
 ```bash
@@ -36,43 +39,53 @@ pushd ../try-me/kind
 
 popd
 
-``` 
+```
+
 to tear it down.
 
 
 ### 2. [Observability](../try-me/observability)
 
 This folder contains Pulumi code to deploy Observability Components into the Kind cluster. 
-Components are deployed as Helm Chart managed by Pulumi. Deploying requires couple steps.
+Components are deployed as [Helm](https://helm.sh/) Chart managed by Pulumi. Deploying requires couple steps.
 [Find out Components deployed](./Components.md)
 
 Inside observability folder.
 
 1. Install libraries. Try-me environment has been prepared using Javascript Pulumi SDK. For those:
+
 ```bash
 
 pushd ../try-me/observability
 npm install
 ```
 
-2. Initialize new Pulumi stack:
+1. Initialize new Pulumi stack:
+
 ```bash
 pulumi stack init localstack --no-select
 ```
-3. Deploy necessary components:
+
+1. Deploy necessary components:
+
 ```bash
 pulumi up localstack
 ```
 
-4. Until now all observability infrastructure are running. We need to auto-instrument the Java application:
+1. Until now all observability infrastructure are running. We need to auto-instrument the Java application:
+
 ```bash
 kubectl patch deployment <your_deployment_name> -n <your_deployment_namespace> -p '{"spec": {"template":{"metadata":{"annotations":{"instrumentation.opentelemetry.io/inject-java":"observability/jvm-autoinstrumentation"}}}} }'
 ```
-5. Get access to Grafana, to get metrics, logs, traces visualized:
+
+1. Get access to Grafana, to get metrics, logs, traces visualized:
+
 ```bash
 kubectl get secret --namespace observability grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo # To retrieve Grafana admin password
 ```
 
+## Results
 
+screenshot
 
 For more details, visit the repository [here](https://github.com/softwaremill/meerkat/tree/main/try-me).

otel/kustomization.yaml

@@ -1,8 +1,6 @@
 apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 namespace: observability
-#configurations:
-#  - collector-transformers.yaml
 resources:
   - jvm-autoinstrumentation.yaml
   - jvm-collector.yaml
@@ -12,4 +10,3 @@ resources:
   - jvm-collector-clusterrole.yaml
   - jvm-collector-clusterrolebinding.yaml
   - jvm-collector-serviceaccount.yaml
-  # - https://github.com/cert-manager/cert-manager/releases/download/v1.14.5/cert-manager.crds.yaml install manually if not using Pulumi