docs: Restructure ruby docs (#1390)

* docs: Restructure ruby docs

Signed-off-by: svrnm <[email protected]>

* Update website_docs/manual.md

* Update website_docs/manual.md

Co-authored-by: Patrice Chalin <[email protected]>

* Update _index.md

Signed-off-by: svrnm <[email protected]>
Co-authored-by: Patrice Chalin <[email protected]>
Co-authored-by: Andrew Hayworth <[email protected]>
Co-authored-by: Robert <[email protected]>

Author: 4 people

website_docs/_index.md

@@ -12,19 +12,7 @@ cascade:
 weight: 24
 ---
 
-This is the OpenTelemetry for Ruby documentation. OpenTelemetry is an observability framework -- an API, SDK, and tools that are designed to aid in the generation and collection of application telemetry data such as metrics, logs, and traces.
-This documentation is designed to help you understand how to get started using OpenTelemetry for Ruby.
-
-## Status and Releases
-
-The current status of the major functional components for OpenTelemetry Ruby is
-as follows:
-
-| Traces  | Metrics | Logs    |
-| ------- | ------- | ------- |
-| Stable | Not Yet Implemented | Not Yet Implemented |
-
-{{% latest_release "ruby" /%}}
+{{% lang_instrumentation_index_head "ruby" /%}}
 
 ## Who's using OpenTelemetry Ruby?
 

website_docs/context-propagation.md

@@ -1,7 +1,10 @@
 ---
 title: Manual Instrumentation
 linkTitle: Manual
-aliases: [/docs/instrumentation/ruby/manual_instrumentation]
+aliases:
+  - /docs/instrumentation/ruby/manual_instrumentation
+  - /docs/instrumentation/ruby/events
+  - /docs/instrumentation/ruby/context-propagation
 weight: 4
 ---
 
@@ -79,13 +82,61 @@ end
 > ⚠ Sampling decisions happen at the moment of span creation.
 > If your sampler considers span attributes when deciding to sample a span, then you _must_ pass those attributes as part of span creation. Any attributes added after creation will not be seen by the sampler, because the sampling decision has already been made.
 
-
 #### Semantic Attributes
 
 Semantic Attributes are attributes that are defined by the [OpenTelemetry Specification][] in order to provide a shared set of attribute keys across multiple languages, frameworks, and runtimes for common concepts like HTTP methods, status codes, user agents, and more. These attributes are available in the [Semantic Conventions gem][semconv-gem].
 
 For details, see [Trace semantic conventions][semconv-spec].
 
-[OpenTelemetry Specification]: {{< relref "/docs/reference/specification" >}}
+### Span Events
+
+An event is a human-readable message on a span that represents "something happening" during it's lifetime. For example, imagine a function that requires exclusive access to a resource that is under a mutex. An event could be created at two points - once, when we try to gain access to the resource, and another when we acquire the mutex.
+
+```ruby
+span.add_event("Acquiring lock")
+if mutex.try_lock
+  span.add_event("Got lock, doing work...")
+  # some code here
+  span.add_event("Releasing lock")
+else
+  span.add_event("Lock already in use")
+end
+```
+
+A useful characteristic of events is that their timestamps are displayed as offsets from the beginning of the span, allowing you to easily see how much time elapsed between them.
+
+Events can also have attributes of their own e.g.
+
+```ruby
+span.add_event("Cancelled wait due to external signal", attributes: { "pid" => 4328, "signal" => "SIGHUP" })
+```
+
+## Context Propagation
+
+> Distributed Tracing tracks the progression of a single Request, called a Trace, as it is handled by Services that make up an Application. A Distributed Trace transverses process, network and security boundaries. [Glossary][]
+
+This requires _context propagation_, a mechanism where identifiers for a trace are sent to remote processes.
+
+> &#8505; The OpenTelemetry Ruby SDK will take care of context propagation as long as your service is leveraging auto-instrumented libraries. Please refer to the [README][auto-instrumentation] for more details.
+
+In order to propagate trace context over the wire, a propagator must be registered with the OpenTelemetry SDK.
+The W3 TraceContext and Baggage propagators are configured by default.
+Operators may override this value by setting `OTEL_PROPAGATORS` environment variable to a comma separated list of [propagators][propagators].
+For example, to add B3 propagation, set `OTEL_PROPAGATORS` to the complete list of propagation formats you wish to support:
+
+```sh
+export OTEL_PROPAGATORS=tracecontext,baggage,b3
+```
+
+Propagators other than `tracecontext` and `baggage` must be added as gem dependencies to your Gemfile, e.g.:
+
+```ruby
+gem 'opentelemetry-propagator-b3'
+```
+
+[glossary]: /docs/concepts/glossary/
+[propagators]: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/propagator
+[auto-instrumentation]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation
 [semconv-gem]: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/semantic_conventions
 [semconv-spec]: {{< relref "/docs/reference/specification/trace/semantic_conventions" >}}
+[OpenTelemetry Specification]: {{< relref "/docs/reference/specification" >}}