nikkie-ftnextの日記

イベントレポートや読書メモを発信

PyCon mini 東海 2025で「PythonでOpenTelemetryの一歩目を体験ワークショップ」をしました #pycontokai

登壇報告 OpenTelemetry Sphinx

はじめに

七尾百合子さん、お誕生日 237日目 おめでとうございます！ nikkieです。

直近の登壇ふりかえりです。

目次

「PythonでOpenTelemetryの一歩目を体験ワークショップ」をしました！

お知らせ

資料

今回は Notion サイトにしました！

当日の様子

15:35〜トーク6・7の裏で、6人くらい（全体の1割程度）で実施しました。

環境構築として uv を入れていただくように案内。
このワークショップでは、FastAPI、HTTPX、google-genai といったライブラリを使った Python コードが用意してあり、そこに OTel1 用のライブラリを追加して計装していきます。
サードパーティライブラリをたくさん使うので、仮想環境まわりを uv に委ねようと inline script metadata を活用しました。
uv がスクリプトごとに、依存ライブラリを入れた仮想環境を用意してくれます！

前半が FastAPI + HTTPX を共通のトレース ID で計装するパート。
後半は google-genai を計装して、LLM API への入力を確認できるようにします。

私が OTel に興味を持ったのは、LLM の deep research の OSS 実装を動かす中で、ブラックボックスでなにやってるか分からない（可観測性がない）という経験からです。
そこにアプローチするのが後半の例なのですが、これだと OTel の理解が偏ってしまうように思い、分散システムのトレースができる例にあたる前半を用意しました。
後半では google-genai に依存する genai-processors の deep research の例を計装し、Gemini がどんなプロンプトを与えられて検索していっているのか、裏側を覗きます（発展の1つ目）

皆さんの進捗を確認しながら進める形式だと60分には分量が多かったようで、後半の発展の2つ目、コレクターへの送信は時間切れで扱えませんでした。
ワークショップでは終始コンソールに出力しましたが、オブザーバビリティバックエンドという概念があり、シグナルをバックエンドに送れます。
ここは OpenTelemetry のコレクター以外にもいろんな選択肢があります（有料・無料含め）

ワークショップとしては OTel が初めてな方の一歩目という位置づけで考えていましたが、OTel サポートしたバックエンドを使っているがその仕組みをちょっとだけ知りたいというユースケースもありそうだなとやってみて思いました。

今のところ思い当たっている反省点が1つあります。
前半の自動計装のところ、uv に仮想環境を管理させ倒している私には自明なのですが、このワンライナーは初見でうっとなるやつでした。

uvx --from opentelemetry-instrumentation \
  --with opentelemetry-distro \
  --with httpx \
  --with opentelemetry-instrumentation-httpx \
  opentelemetry-instrument \
    --traces_exporter console \
    --metrics_exporter none \
    --logs_exporter none \
    python client.py

opentelemetry-instrumentコマンドが重要なんですが、これだとuvxの--fromと--with（uv が管理する仮想環境への追加の依存の指定）に目がいっちゃいますよね

Notion サイトまわり

最初は2024同様に GitHub Pages を考えていました2。
GitHub Pages にすると、パブリックリポジトリに置くことになります（プライベートにするには GitHub アカウントを有料化）。

ワークショップ資料以外はプライベート（非公開）にしてみたいと思ったときに、自作の sphinx-notion を思い出しました。
これで（※機能不足なので手作業も交えて） Notion サイトにしています

sphinx-revealjs 製スライド（単一ドキュメント）からの変換ではなく、複数ドキュメントとから変換する用途で sphinx-notion を使うと、色々と機能追加の余地に気づきます。

  • テキストにURLをつける実装が壊れていた -> 修正
  • 1ファイルでアップロードしようとして、子要素は一度に100までと気付く。ここはワークアラウンド + 手作業で分解
  • admonition のうち、note, hint, tip のサポート（Notion の callout として）
  • 引用のサポート
  • ordered list のサポート
  • 斜体のサポート
  • code-block の:caption:で Notion のコードにも caption
  • literalinclude したときのファイル末尾の改行を削除
  • マークアップのために付与した半角スペースを削除していたが、URL の前後の空白は欲しい
    • 例「ここで **強調** です」

一部はトークを聞きながら、SWE-1.5 に実装を進めてもらいました3。
当日にリリース

現在も機能強化は続きます

終わりに

PyCon mini 東海 2025 で OTel 一歩目ワークショップをやりました！
ご参加いただいた皆さま、ありがとうございました。

ワークショップ資料には自作の sphinx-notion を利用しました。
当事者になると機能追加の色々な伸びしろに気づくもので、ワークショップだけでなく sphinx-notion の機能追加も進められました。
両方やればええんや！（当日懇親会に行く余力が残らなかった要因でもあります4）

  1. ワークショップで伝えましたが、OpenTelemetry の略称です。ref: https://opentelemetry.io/ja/docs/concepts/glossary/#otel↩
  2. ↩
  3. 使い切りました！ ↩
  4. 精根尽き果てたところをえいがさきに救われました ↩