<p>少し前に比べるとだいぶOpenTelemetry界隈もにぎやかになってきたなーと感じる今日この頃です。私も２年ほど前からコントリビュートしたりブログ記事を書いたりしていましたが、どこかで同期的に開催されるイベントにも参加したいなーと思っています。</p>
<p>さて、皆さんは普段アプリケーションを計装したり計装用のライブラリを書く際は、ローカルでの動作確認をどのように行っているでしょうか？</p>
<p>自身の観測範囲内ではローカルでjaegerやGrafanaなどを上げている人が多い印象ですが、今回新たな方法としてターミナル上でOpenTelemetryを閲覧できる自作ツール「otel-tui」をご紹介できればと思います。</p>
<p><span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__34f1f9201ac9c" src="https://embed.zenn.studio/card#zenn-embedded__34f1f9201ac9c" data-content="https%3A%2F%2Fgithub.com%2Fymtdzzz%2Fotel-tui" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://github.com/ymtdzzz/otel-tui" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://github.com/ymtdzzz/otel-tui</a></p>
<p>なお、今回の記事では使い方などユーザー向けの内容となっているので、実装周りの詳細については下記のブログ記事をご参照ください。</p>
<p><span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__2ceb79dcfa289" src="https://embed.zenn.studio/card#zenn-embedded__2ceb79dcfa289" data-content="https%3A%2F%2Fymtdzzz.dev%2Fpost%2Fview-otel-with-otel-tui%2F" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://ymtdzzz.dev/post/view-otel-with-otel-tui/" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://ymtdzzz.dev/post/view-otel-with-otel-tui/</a></p>
<h1 id="%E3%83%A2%E3%83%81%E3%83%99%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3">
<a class="header-anchor-link" href="#%E3%83%A2%E3%83%81%E3%83%99%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3" aria-hidden="true"></a> モチベーション</h1>
<h2 id="%E3%83%AD%E3%83%BC%E3%82%AB%E3%83%AB%E3%81%A7%E3%81%AE%E9%96%8B%E7%99%BA%E3%81%AB%E3%80%8C%E3%81%A1%E3%82%87%E3%81%86%E3%81%A9%E8%89%AF%E3%81%84%E3%80%8D%E3%83%84%E3%83%BC%E3%83%AB%E3%81%8C%E3%81%BB%E3%81%97%E3%81%8B%E3%81%A3%E3%81%9F">
<a class="header-anchor-link" href="#%E3%83%AD%E3%83%BC%E3%82%AB%E3%83%AB%E3%81%A7%E3%81%AE%E9%96%8B%E7%99%BA%E3%81%AB%E3%80%8C%E3%81%A1%E3%82%87%E3%81%86%E3%81%A9%E8%89%AF%E3%81%84%E3%80%8D%E3%83%84%E3%83%BC%E3%83%AB%E3%81%8C%E3%81%BB%E3%81%97%E3%81%8B%E3%81%A3%E3%81%9F" aria-hidden="true"></a> ローカルでの開発に「ちょうど良い」ツールがほしかった</h2>
<p>これまでの自身の経験から、ローカルでシグナルを出力して確認したいユースケースとしては下記のようなものがありました。</p>
<ul>
<li>トレースが意図したとおり紐付いているか確認したい
<ul>
<li>contextの欠落など実装レベルの動作確認を行いたい場合</li>
</ul>
</li>
<li>想定通りのattributeが設定されているか確認したい
<ul>
<li>ベンダー側で指定したattributeがついてないと上手く表示されない場合</li>
<li>独自のattributeを指定している場合</li>
</ul>
</li>
</ul>
<p>現状、ローカルでシグナル（主にトレース）の確認をする方法として下記が挙げられると思います。</p>
<ul>
<li>ローカルにjaeger（all-in-oneなどUI付きのもの）やGrafana Tempoコンテナを上げて送信＆閲覧する</li>
<li>Exporterを活用して標準出力やファイルなどに出力し確認する</li>
</ul>
<p>ただ、これらの方法には下記の限界があります（自分は普段ローカルでjaeger立ててました）。</p>
<p>ローカルにjaeger（all-in-oneなどUI付きのもの）やGrafana Tempoなどのコンテナを上げて送信＆閲覧する</p>
<ul>
<li>ローカルで動かすにはそれなりに重い</li>
<li>productionレベルの機能群がtoo muchすぎる（サービスマップなど）</li>
<li>リアルタイムに出力内容をサクサク閲覧する　みたいなのがしにくい</li>
</ul>
<p>Exporterを活用して標準出力やファイルなどに出力し確認する ※こちらはやったことないので想像です</p>
<ul>
<li>可読性が低い（トレース紐付け状態などはTrace IDやparent Span ID等でgrepするなど）</li>
</ul>
<p>このように、production gradeの製品をコンテナで動かすのはtoo muchすぎるし、テキストベースだと閲覧しにくい・・・ということで、それぞれいいとこ取りできるようなツールが欲しいなと思ったのがきっかけです。</p>
<h2 id="%E9%A1%9E%E4%BC%BC%E3%83%84%E3%83%BC%E3%83%AB%E3%82%82%E3%81%82%E3%82%8B%E3%81%91%E3%82%8C%E3%81%A9">
<a class="header-anchor-link" href="#%E9%A1%9E%E4%BC%BC%E3%83%84%E3%83%BC%E3%83%AB%E3%82%82%E3%81%82%E3%82%8B%E3%81%91%E3%82%8C%E3%81%A9" aria-hidden="true"></a> 類似ツールもあるけれど</h2>
<p>このツールを作成するきっかけにもなった「<a href="https://github.com/CtrlSpice/otel-desktop-viewer" target="_blank" rel="nofollow noopener noreferrer">otel-desktop-viewer</a>」があります。このツールもローカルでOpenTelemetryで出力されたシグナルを閲覧することにフォーカスしたもので非常に使いやすいです。</p>
<p>ただ、ある程度の流量を長時間流し続けるとクエリや画面描画にもたついたりする（※マシンスペックによる）ことがあり、自分としてはブラウザを開かずにリアルタイムで閲覧でき、かつパフォーマンス的にも安定した自分好みのツールを作りたくなりました。</p>
<h1 id="%E7%89%B9%E5%BE%B4%E3%83%BB%E6%A9%9F%E8%83%BD">
<a class="header-anchor-link" href="#%E7%89%B9%E5%BE%B4%E3%83%BB%E6%A9%9F%E8%83%BD" aria-hidden="true"></a> 特徴・機能</h1>
<p>画面はこんな感じです。</p>
<p>&lt;Trace&gt;</p>
<p><img src="https://storage.googleapis.com/zenn-user-upload/28006eceaf2e-20240626.png" loading="lazy" class="md-img"></p>
<p><img src="https://storage.googleapis.com/zenn-user-upload/a6f115dc1829-20240626.png" loading="lazy" class="md-img"></p>
<p>&lt;Log&gt;</p>
<p><img src="https://storage.googleapis.com/zenn-user-upload/4457bd016019-20240626.png" loading="lazy" class="md-img"></p>
<p>主な特徴や機能は下記の通りです。</p>
<ul>
<li>機能面
<ul>
<li>トレース
<ul>
<li>サービススパン単位のリスト表示及びサービス名による検索</li>
<li>Attributeなどの詳細情報表示</li>
<li>トレースのグラフ表示（waterfall diagram）</li>
</ul>
</li>
<li>ログ
<ul>
<li>ログのリスト表示及び検索</li>
<li>ログから該当トレースへのジャンプ</li>
</ul>
</li>
</ul>
</li>
<li>パフォーマンス
<ul>
<li>軽量かつリアルタイムの画面更新（シグナル受信と画面描画の非同期化）</li>
<li>長時間ある程度の流量を流し続けてもメモリリークしない（データローテーション）</li>
</ul>
</li>
</ul>
<h2 id="todos">
<a class="header-anchor-link" href="#todos" aria-hidden="true"></a> TODOs</h2>
<p>逆に、まだ足りてない機能もたくさんあります</p>
<ul>
<li>柔軟な設定
<ul>
<li>画面更新頻度</li>
<li>バッファーサイズ</li>
</ul>
</li>
<li>メトリクス取得と表示</li>
<li>挙動の安定性
<ul>
<li>ごくまれに長時間利用しているとプロセスが落ちたり</li>
</ul>
</li>
<li>一貫したキーバインド</li>
<li>UI周り
<ul>
<li>ナビゲーション
<ul>
<li>トレース→ログ詳細→元のトレースに戻るなど</li>
</ul>
</li>
<li>テキストの折返し、waterfall diagram</li>
<li>デバッグログ</li>
</ul>
</li>
</ul>
<h1 id="%E4%BD%BF%E3%81%84%E6%96%B9">
<a class="header-anchor-link" href="#%E4%BD%BF%E3%81%84%E6%96%B9" aria-hidden="true"></a> 使い方</h1>
<p>せっかくなのである程度の流量を体験できる「<a href="https://github.com/open-telemetry/opentelemetry-demo" target="_blank" rel="nofollow noopener noreferrer">opentelemetry-demo</a>」から出力されるシグナルを用いて使い方をご紹介できればと思います。</p>
<h2 id="%E3%80%8Cotel-tui%E3%80%8D%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB">
<a class="header-anchor-link" href="#%E3%80%8Cotel-tui%E3%80%8D%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB" aria-hidden="true"></a> 「otel-tui」のインストール</h2>
<p>Homebrewでインストールできます。</p>
<div class="code-block-container"><pre><code>$ brew install ymtdzzz/tap/otel-tui
</code></pre></div><p>Homebrew以外のパッケージ管理ツールにはまだ対応していないので、Homebrewが利用できない場合<a href="https://github.com/ymtdzzz/otel-tui/releases" target="_blank" rel="nofollow noopener noreferrer">リリースページ</a>からバイナリを落としていただくか、ソースからビルドしてください。</p>
<p>helpやversionが出ればOKです。</p>
<div class="code-block-container"><pre><code>$ otel-tui -v
otel-tui version 0.1.2

$ otel-tui -h
Usage:
  otel-tui [flags]

Flags:
      --grpc int      The port number on which we listen for OTLP grpc payloads (default 4317)
  -h, --help          help for otel-tui
      --host string   The host where we expose our all endpoints (OTLP receivers and browser) (default "0.0.0.0")
      --http int      The port number on which we listen for OTLP http payloads (default 4318)
  -v, --version       version for otel-tui
</code></pre></div><h2 id="%E8%A8%88%E8%A3%85%E6%B8%88%E3%81%BF%E3%82%A2%E3%83%97%E3%83%AA%E3%81%AE%E5%90%91%E3%81%8D%E5%85%88%E5%A4%89%E6%9B%B4">
<a class="header-anchor-link" href="#%E8%A8%88%E8%A3%85%E6%B8%88%E3%81%BF%E3%82%A2%E3%83%97%E3%83%AA%E3%81%AE%E5%90%91%E3%81%8D%E5%85%88%E5%A4%89%E6%9B%B4" aria-hidden="true"></a> 計装済みアプリの向き先変更</h2>
<p>今回は「<a href="https://github.com/open-telemetry/opentelemetry-demo" target="_blank" rel="nofollow noopener noreferrer">opentelemetry-demo</a>」を使うのでリポジトリをクローンし、必要な設定を行います。</p>
<h3 id="collector%E3%81%AE%E5%90%91%E3%81%8D%E5%85%88%E4%BF%AE%E6%AD%A3">
<a class="header-anchor-link" href="#collector%E3%81%AE%E5%90%91%E3%81%8D%E5%85%88%E4%BF%AE%E6%AD%A3" aria-hidden="true"></a> Collectorの向き先修正</h3>
<p>opentelemetry-demoは複数のマイクロサービスで構成されていますが、すべてのシグナルはOpenTelemetry Collectorに集約されています。そのため、Collectorのexporterの向き先をotel-tuiに向けるだけでOKです。</p>
<div class="code-block-container"><pre class="language-yaml"><code class="language-yaml"><span class="token comment"># src/otelcollector/otelcol-config-extras.yml</span>
<span class="token key atrule">exporters</span><span class="token punctuation">:</span>
  <span class="token key atrule">otlp</span><span class="token punctuation">:</span>
    <span class="token key atrule">endpoint</span><span class="token punctuation">:</span> host.docker.internal<span class="token punctuation">:</span><span class="token number">4317</span>

<span class="token key atrule">service</span><span class="token punctuation">:</span>
  <span class="token key atrule">pipelines</span><span class="token punctuation">:</span>
    <span class="token key atrule">traces</span><span class="token punctuation">:</span>
      <span class="token key atrule">exporters</span><span class="token punctuation">:</span> <span class="token punctuation">[</span>spanmetrics<span class="token punctuation">,</span> otlp<span class="token punctuation">]</span>
    <span class="token key atrule">logs</span><span class="token punctuation">:</span>
      <span class="token key atrule">exporters</span><span class="token punctuation">:</span> <span class="token punctuation">[</span>otlp<span class="token punctuation">]</span>
</code></pre></div><h3 id="%E3%82%B3%E3%83%B3%E3%83%86%E3%83%8A%E3%81%8B%E3%82%89%E3%83%9B%E3%82%B9%E3%83%88%E3%81%AE%E3%83%9D%E3%83%BC%E3%83%88%E3%81%B8%E3%81%AE%E9%80%9A%E4%BF%A1%E3%82%92%E8%A8%B1%E5%8F%AF-%E2%80%BBdocker-desktop%E4%BB%A5%E5%A4%96%E3%81%AE%E5%A0%B4%E5%90%88%E3%81%AE%E3%81%BF">
<a class="header-anchor-link" href="#%E3%82%B3%E3%83%B3%E3%83%86%E3%83%8A%E3%81%8B%E3%82%89%E3%83%9B%E3%82%B9%E3%83%88%E3%81%AE%E3%83%9D%E3%83%BC%E3%83%88%E3%81%B8%E3%81%AE%E9%80%9A%E4%BF%A1%E3%82%92%E8%A8%B1%E5%8F%AF-%E2%80%BBdocker-desktop%E4%BB%A5%E5%A4%96%E3%81%AE%E5%A0%B4%E5%90%88%E3%81%AE%E3%81%BF" aria-hidden="true"></a> コンテナからホストのポートへの通信を許可 ※Docker Desktop以外の場合のみ</h3>
<p>LinuxなどDocker Desktopを利用していない場合、host.docker.internalをコンテナ内部から解決できるように設定してあげます。</p>
<div class="code-block-container"><pre class="language-yaml"><code class="language-yaml">  <span class="token comment"># docker-compose.minimal.yml</span>
  <span class="token comment"># OpenTelemetry Collector</span>
  <span class="token key atrule">otelcol</span><span class="token punctuation">:</span>
    <span class="token key atrule">image</span><span class="token punctuation">:</span> $<span class="token punctuation">{</span>COLLECTOR_CONTRIB_IMAGE<span class="token punctuation">}</span>
    <span class="token key atrule">container_name</span><span class="token punctuation">:</span> otel<span class="token punctuation">-</span>col
		<span class="token comment"># ...</span>
    <span class="token key atrule">extra_hosts</span><span class="token punctuation">:</span>
      <span class="token punctuation">-</span> <span class="token string">"host.docker.internal:host-gateway"</span>
</code></pre></div><h2 id="otel-tui%E3%81%A8%E8%A8%88%E8%A3%85%E6%B8%88%E3%81%BF%E3%82%A2%E3%83%97%E3%83%AA%E3%82%92%E8%B5%B7%E5%8B%95">
<a class="header-anchor-link" href="#otel-tui%E3%81%A8%E8%A8%88%E8%A3%85%E6%B8%88%E3%81%BF%E3%82%A2%E3%83%97%E3%83%AA%E3%82%92%E8%B5%B7%E5%8B%95" aria-hidden="true"></a> otel-tuiと計装済みアプリを起動</h2>
<p>それぞれ別タブなどで起動します。</p>
<div class="code-block-container"><pre class="language-bash"><code class="language-bash"><span class="token comment"># otel-tuiのパスが通っているところならどこでも</span>
$ otel-tui
</code></pre></div><div class="code-block-container"><pre class="language-bash"><code class="language-bash"><span class="token comment"># opentelemetry-demoリポジトリのroot</span>
$ <span class="token function">make</span> start-minimal
</code></pre></div><h2 id="%E3%83%87%E3%83%BC%E3%82%BF%E3%82%92%E6%8E%A2%E7%B4%A2%E3%81%99%E3%82%8B">
<a class="header-anchor-link" href="#%E3%83%87%E3%83%BC%E3%82%BF%E3%82%92%E6%8E%A2%E7%B4%A2%E3%81%99%E3%82%8B" aria-hidden="true"></a> データを探索する</h2>
<p>少しするとotel-tui上で、先述したような画面でずらずらとシグナルが流れてくるかと思います。</p>
<p>トレースとログは<code>Tab</code>キーで切り替えが可能で、各ペインもタイトル（<code>Details(d)</code>など）に記載のあるキーを入力することで移動することが可能です。</p>
<p>ちょっと多すぎるなということで<code>/</code>キーで検索ボックスに移動し、<code>product</code>とかで検索（<code>Enter</code>キー）してみます。</p>
<p><img src="https://storage.googleapis.com/zenn-user-upload/da43cab399d9-20240626.png" loading="lazy" class="md-img"></p>
<p>productというprefixのサービスに関連するスパンにフィルタリングされました。Detailsペインに現在フォーカスされているSpanのリソース情報、属性などの情報が表示されています。ちなみに、Detailsペインにフォーカスした状態で<code>Enter</code>キーを押下するとツリーを折りたたみ可能です。</p>
<p>TracesペインでフォーカスしているSpanを<code>Enter</code>キーで選択すると、トレース詳細画面に飛びます。</p>
<p><img src="https://storage.googleapis.com/zenn-user-upload/32b5f301c594-20240626.png" loading="lazy" class="md-img"></p>
<p>Trace Timelineでは実装の都合上矢印キーのみでの操作となります（他は<code>hjkl</code>でも操作可能）。これまたフォーカスするとDetailsに詳細情報が出てきます。Logsペインには当該トレースに関連性のあるログが出てきます。</p>
<p><code>Esc</code>キーでトレース一覧に戻り、<code>Tab</code>キーでログ画面に切り替えてみます。</p>
<p><img src="https://storage.googleapis.com/zenn-user-upload/63b5308dfc65-20240626.png" loading="lazy" class="md-img"></p>
<p>トレースと同じように適当なワードで検索を行いつつ、Detailsを見てみると<code>LogRecord</code>&gt;<code>trace id</code>にリンク絵文字（🔗）が付与されているものがあります。</p>
<p>そのAttributeにフォーカスを合わせて<code>Enter</code>キーを押下すると、該当のトレース詳細画面に遷移することが可能です。</p>
<p>このように、計装したアプリから想定通りの情報が渡ってきているか、きちんと紐付いているかなど実装観点での動作確認に役立てることができます。</p>
<h1 id="%E3%81%95%E3%81%84%E3%81%94%E3%81%AB">
<a class="header-anchor-link" href="#%E3%81%95%E3%81%84%E3%81%94%E3%81%AB" aria-hidden="true"></a> さいごに</h1>
<p>まだまだ機能も足りなく荒削りな部分が多いですが、個人的には割と結構使いやすくて気に入っています。</p>
<p>使ってみた方は是非issueやXなどでフィードバックいただけますと幸いです！</p>


ターミナルでOpenTelemetryのトレースを閲覧できるツール「otel-tui」を作りました

ローカルでの開発に「ちょうど良い」ツールがほしかった

コンテナからホストのポートへの通信を許可 ※Docker Desktop以外の場合のみ

Discussion