docs(sample-app): add beginner-friendly LLM tracing example (#4069)

[NishchayMahor]

Adds a short, heavily-commented walkthrough at `packages/sample-app/sample_app/beginner_tracing_example.py` that introduces `Traceloop.init`, `@workflow`, and `@task` against a single OpenAI call.

Closes #4069.

The existing examples in `sample-app/` are great references once you already know the SDK shape, but they assume you do. This one starts from `Traceloop.init` and works up to a two-task workflow so a first-time user can copy it, run it, and see the trace structure that everything else in the repo produces.

Also replaces the sample-app README placeholder (`Project description here.`) with a short paragraph that points new users at this example first.

```bash
export OPENAI_API_KEY=sk-...
poetry run python sample_app/beginner_tracing_example.py
```

```
$ uvx ruff check packages/sample-app/sample_app/beginner_tracing_example.py
All checks passed!

$ uvx ruff format --check packages/sample-app/sample_app/beginner_tracing_example.py
1 file already formatted
```

Summary by CodeRabbit

• Documentation

  • Enhanced sample app README with a “Start here if you’re new” quick-start, runnable walkthrough, instructions to switch to real tracing backends, and an overview of additional provider/scenario examples.

• New Features

  • Added a beginner tracing example that demonstrates instrumented AI chat workflows with real-time spans emitted to stdout and prints example outputs.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bfeccd7e-9fa2-4930-9566-c017e397ce60

📥 Commits

Reviewing files that changed from the base of the PR and between f6be672 and 06c2055.

📒 Files selected for processing (2)

• packages/sample-app/README.md
• packages/sample-app/sample_app/beginner_tracing_example.py

✅ Files skipped from review due to trivial changes (1)

• packages/sample-app/README.md

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/sample-app/sample_app/beginner_tracing_example.py

---

📝 Walkthrough

Walkthrough

This PR adds README instructions and a self-contained beginner tracing example that initializes Traceloop with a ConsoleSpanExporter, creates an OpenAI client, defines two traced tasks and a traced workflow that call OpenAI chat completions, and provides a main entrypoint to run the workflow.

Changes

Beginner-Friendly LLM Tracing Example

Layer / File(s)	Summary
Documentation and overview packages/sample-app/README.md, packages/sample-app/sample_app/beginner_tracing_example.py (header)	README updated with runnable instructions and link to the beginner example; example file header/docstring explains the minimal walkthrough, three-part structure, and exporter behavior.
Setup and configuration packages/sample-app/sample_app/beginner_tracing_example.py (imports, init, client)	Traceloop initialized with app_name="beginner-tracing-example", disable_batch=True, and exporter=ConsoleSpanExporter() for stdout spans; a module-level client = OpenAI() is created.
Traced tasks and workflow execution packages/sample-app/sample_app/beginner_tracing_example.py (tasks, workflow, entrypoint)	Defines @task functions tell_joke() and explain_joke(joke) that call OpenAI chat completions and return text, a @workflow(name="joke_and_explanation") that calls both and prints results, and a __main__ entrypoint to execute the workflow.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A hop, a prompt, a trace in flight,
I tell a joke and shed some light,
Spans hop to stdout, clear and bright,
Workflow hums, tasks pair just right,
New folks grin and trace the sight!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding a beginner-friendly LLM tracing example to the sample app.
Linked Issues check	✅ Passed	All requirements from issue #4069 are met: minimal setup guide, basic LLM call example, tracing demonstration, trace output visibility, and copyable format for beginners.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the linked issue: beginner example file, README updates, and exporter configuration. No unrelated modifications present.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/sample-app/README.md`:
- Around line 9-12: Update the run command in the README code block so it uses
the project’s preferred package runner: replace the line "poetry run python
sample_app/beginner_tracing_example.py" with "uv run python
sample_app/beginner_tracing_example.py" in the README.md code block (the snippet
that also sets OPENAI_API_KEY) to keep the instructions consistent with the rest
of the repo.

In `@packages/sample-app/sample_app/beginner_tracing_example.py`:
- Around line 12-14: Update the embedded run instructions in the
beginner_tracing_example.py docstring to use the uv package manager instead of
poetry: locate the usage lines that currently read "poetry run python
sample_app/beginner_tracing_example.py" in the file's top-level docstring (or
usage block) and change them to "uv run python
sample_app/beginner_tracing_example.py" so package-management commands follow
the repository guideline; ensure the OPENAI_API_KEY export line remains
unchanged.
- Around line 27-30: The example exits early because Traceloop.init is called
without TRACELOOP_API_KEY or an exporter/processor; update the init call in
beginner_tracing_example.py to supply a stdout debug pipeline by passing
processor=SimpleSpanProcessor(ConsoleSpanExporter()) (import ConsoleSpanExporter
and SimpleSpanProcessor from opentelemetry.sdk.trace.export and
opentelemetry.sdk.trace respectively) so spans print to stdout even when
TRACELOOP_API_KEY is missing, and update the docstring run instruction to use
"uv run ..." instead of "poetry run ...".

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ab97d2cd-216e-45cd-8957-7051c5fa0dda

📥 Commits

Reviewing files that changed from the base of the PR and between b39151b and f6be672.

📒 Files selected for processing (2)

• packages/sample-app/README.md
• packages/sample-app/sample_app/beginner_tracing_example.py

[NishchayMahor]

Thanks @coderabbitai — addressed all three in 06c2055:

• poetry run → uv run in both the docstring and the README, matching the repo guideline.
• Silent example — wired `exporter=ConsoleSpanExporter()` into `Traceloop.init` so spans land on stdout without needing `TRACELOOP_API_KEY` or an OTLP endpoint. Docstring + README updated to say so, with a note that real backends should drop the explicit exporter and use `TRACELOOP_API_KEY` / `OTEL_EXPORTER_OTLP_*` instead.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@NishchayMahor Thanks for the update! All three changes look great:

• ✅ uv run alignment keeps the example consistent with the repo's toolchain.
• ✅ Wiring in ConsoleSpanExporter() makes the example truly zero-config — new users can run it immediately without any credentials or backend setup.
• ✅ The note pointing toward TRACELOOP_API_KEY / OTEL_EXPORTER_OTLP_* for real deployments is a nice touch that bridges the beginner example to production use.

The changes address the original concerns well. 🐇

---

If you found this review helpful, would you consider giving us a shout-out on X?

Thank you for using CodeRabbit!