Skip to content

Commit 2a49e39

Browse files
kylehounslowkylehounslow
committed
docs: refine landing page card content and section ordering
- Update card bullet points for accuracy (log-trace correlation, PPL/PromQL, SDKs) - Mention Prometheus metrics in intro - Move Why section above Quickstarts - Hyperlink semantic conventions in Why section - Use hybrid intro text preserving original voice Signed-off-by: Kyle Hounslow <kylhouns@amazon.com>
1 parent 013722f commit 2a49e39

6 files changed

Lines changed: 111 additions & 45 deletions

File tree

‎docs/starlight-docs/astro.config.mjs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,16 @@ export default defineConfig({
1616
logo: {
1717
src: './src/assets/opensearch-logo-darkmode.svg',
1818
},
19+
editLink: {
20+
baseUrl: 'https://github.com/opensearch-project/observability-stack/edit/main/docs/starlight-docs/',
21+
},
1922
customCss: [
2023
'./src/styles/custom.css',
2124
],
2225
social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/opensearch-project/observability-stack' }],
2326
components: {
2427
Header: './src/components/CustomHeader.astro',
28+
PageSidebar: './src/components/PageSidebar.astro',
2529
},
2630
sidebar: [
2731
{

‎docs/starlight-docs/public/icons/apm_trace.svg‎

Lines changed: 0 additions & 14 deletions
This file was deleted.

‎docs/starlight-docs/public/icons/app_monitoring.svg‎

Lines changed: 0 additions & 18 deletions
This file was deleted.

‎docs/starlight-docs/public/icons/app_visualize.svg‎

Lines changed: 20 additions & 0 deletions
Loading

‎docs/starlight-docs/src/components/PageSidebar.astro‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
import MobileTableOfContents from 'virtual:starlight/components/MobileTableOfContents';
3+
import TableOfContents from 'virtual:starlight/components/TableOfContents';
4+
5+
const { slug, editUrl: starlightEditUrl } = Astro.locals.starlightRoute;
6+
const editUrl = starlightEditUrl?.href || `https://github.com/opensearch-project/observability-stack/edit/main/docs/starlight-docs/src/content/docs/${slug || 'index'}.mdx`;
7+
const issueUrl = `https://github.com/opensearch-project/observability-stack/issues/new?title=Docs+feedback:+${encodeURIComponent(slug || 'index')}&labels=documentation`;
8+
---
9+
10+
{
11+
Astro.locals.starlightRoute.toc && (
12+
<>
13+
<div class="lg:sl-hidden">
14+
<MobileTableOfContents />
15+
</div>
16+
<div class="right-sidebar-panel sl-hidden lg:sl-block">
17+
<div class="sl-container">
18+
<TableOfContents />
19+
<div class="sidebar-links">
20+
<a href={editUrl} target="_blank" rel="noopener"><svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor" style="vertical-align: -2px; margin-right: 4px;"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg>Edit this page on GitHub</a>
21+
<a href={issueUrl} target="_blank" rel="noopener">💬 Report a docs issue</a>
22+
</div>
23+
</div>
24+
</div>
25+
</>
26+
)
27+
}
28+
29+
<style>
30+
@layer starlight.core {
31+
.right-sidebar-panel {
32+
padding: 1rem var(--sl-sidebar-pad-x);
33+
}
34+
.sl-container {
35+
width: calc(var(--sl-sidebar-width) - 2 * var(--sl-sidebar-pad-x));
36+
}
37+
.right-sidebar-panel :global(h2) {
38+
color: var(--sl-color-white);
39+
font-size: var(--sl-text-h5);
40+
font-weight: 600;
41+
line-height: var(--sl-line-height-headings);
42+
margin-bottom: 0.5rem;
43+
}
44+
.right-sidebar-panel :global(:where(a)) {
45+
display: block;
46+
font-size: var(--sl-text-xs);
47+
text-decoration: none;
48+
color: var(--sl-color-gray-3);
49+
overflow-wrap: anywhere;
50+
}
51+
.right-sidebar-panel :global(:where(a):hover) {
52+
color: var(--sl-color-white);
53+
}
54+
.sidebar-links {
55+
margin-top: 1.5rem;
56+
padding-top: 1rem;
57+
border-top: 1px solid var(--sl-color-gray-6);
58+
display: flex;
59+
flex-direction: column;
60+
gap: 0.5rem;
61+
}
62+
@media (min-width: 72rem) {
63+
.sl-container {
64+
max-width: calc(
65+
(
66+
(
67+
100vw - var(--sl-sidebar-width) - 2 * var(--sl-content-pad-x) - 2 *
68+
var(--sl-sidebar-pad-x)
69+
) * 0.25
70+
)
71+
);
72+
}
73+
}
74+
}
75+
</style>

‎docs/starlight-docs/src/content/docs/index.mdx‎

Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,25 @@ import { LinkCard, CardGrid, Tabs, TabItem, Aside } from '@astrojs/starlight/com
77
import IconCard from '../../components/IconCard.astro';
88
import IconCardGrid from '../../components/IconCardGrid.astro';
99

10-
OpenSearch Observability Stack is an **open-source, OpenTelemetry-native observability platform** ([GitHub](https://github.com/opensearch-project/observability-stack)) for monitoring services, infrastructure, and AI agents. Install locally via Docker Compose — traces, logs, metrics, service maps, and agent tracing out of the box.
10+
OpenSearch Observability Stack is an **open-source, OpenTelemetry-native observability platform** ([GitHub](https://github.com/opensearch-project/observability-stack)) for monitoring services, infrastructure, and AI agents. Install locally via Docker Compose — traces, logs, Prometheus metrics, service maps, and agent tracing out of the box.
1111

1212
## What You Can Do
1313

1414
<IconCardGrid>
15-
<IconCard title="Traces, Logs & Metrics" icon="/docs/icons/app_monitoring.svg" items={["Collect via OTLP", "Correlate across signals", "Search with PPL and PromQL"]} href="/docs/investigate/discover-logs/" />
15+
<IconCard title="Traces, Logs & Metrics" icon="/docs/icons/app_visualize.svg" items={["Collect via OTLP", "Log-trace correlation", "Search with PPL and PromQL"]} href="/docs/investigate/discover-logs/" />
1616
<IconCard title="Application Monitoring" icon="/docs/icons/app_apm.svg" items={["Auto-generated service maps", "RED metrics from traces", "Latency and error tracking"]} href="/docs/apm/" />
17-
<IconCard title="AI Agent Observability" icon="/docs/icons/app_ml.svg" items={["Trace LLM calls and tool use", "Agent execution graphs", "Token usage and cost tracking"]} href="/docs/ai-observability/" />
17+
<IconCard title="AI Agent Observability" icon="/docs/icons/app_ml.svg" items={["Trace LLM calls, token usage, and tool use", "Agent execution graphs", "Python and JavaScript SDKs"]} href="/docs/ai-observability/" />
1818
<IconCard title="Dashboards & Alerting" icon="/docs/icons/app_dashboard.svg" items={["Custom dashboards", "Anomaly detection", "Slack, email, webhook alerts"]} href="/docs/dashboards/" />
1919
</IconCardGrid>
2020

21+
## Why Observability Stack?
22+
23+
- **Open source**: Fully open source, no vendor lock-in, self-host everything
24+
- **OpenTelemetry-native**: All data ingestion uses OTel protocols and [semantic conventions](https://opentelemetry.io/docs/specs/semconv/)
25+
- **GenAI-first**: Purpose-built views for AI agent tracing using standard `gen_ai.*` attributes
26+
- **Local-first**: Runs entirely on your machine via Docker Compose — no cloud account required
27+
- **Production path**: Same components (OpenSearch, Prometheus, OTel Collector) scale to production
28+
2129
## Quickstarts
2230

2331
<LinkCard title="Install & Explore" href="/docs/get-started/" description="Install the stack and explore traces already flowing from the built-in example services." />
@@ -28,16 +36,7 @@ OpenSearch Observability Stack is an **open-source, OpenTelemetry-native observa
2836
The stack optionally ships with example services — a multi-agent travel planner, weather agent, and events agent that generate agent traces automatically. You can also enable the [OpenTelemetry Demo](https://opentelemetry.io/docs/demo/architecture/), a full microservices e-commerce app for realistic telemetry. Install, open Dashboards, and start exploring — no instrumentation needed.
2937
</Aside>
3038

31-
## Why Observability Stack?
32-
33-
- **Open source**: Fully open source, no vendor lock-in, self-host everything
34-
- **OpenTelemetry-native**: All data ingestion uses OTel protocols and semantic conventions
35-
- **GenAI-first**: Purpose-built views for AI agent tracing using standard `gen_ai.*` attributes
36-
- **Local-first**: Runs entirely on your machine via Docker Compose — no cloud account required
37-
- **Production path**: Same components (OpenSearch, Prometheus, OTel Collector) scale to production
38-
3939
## Community
4040

41-
- [GitHub](https://github.com/opensearch-project/observability-stack) — issues, PRs, discussions
42-
- [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) — the standard we follow
41+
- [GitHub](https://github.com/opensearch-project/observability-stack) — issues, PRs, and discussions
4342
- [Contributing guide](/docs/contributing/) — how to contribute

0 commit comments

Comments
 (0)