ウィジェット

アクティブな接続、QPS、サーバの状態を、アプリを開かずにホーム画面やデスクトップから監視します。

場所： Widget › 一般

「Calíopeウィジェット」は、サーバ（MySQL、MariaDB、PostgreSQL、SQL Server、Oracle Database、ClickHouse）の主要なメトリクスを、アプリケーションを開かなくても、macOSのデスクトップや、iPhoneとiPadのホーム画面にリアルタイムで表示します。

表示されるメトリクス：
- 「アクティブな接続」 — 開いている接続の数と、サーバで設定されている最大数。
- QPSまたはTPS — サーバのスループット：MySQL、MariaDB、ClickHouseでは1秒あたりのクエリー数、Oracleでは1秒あたりに実行された文の数、SQL Serverでは1秒あたりのバッチ数、PostgreSQLでは1秒あたりのトランザクション数。異なる2つの量なので、どちらを見ているかはラベルが示します。
- 「稼働時間」 — サーバが動いている時間で、Nd Nh Nmの形式。
- 「アクティブなスレッド」（ウィジェットのサイズが中と大） — 実行中のスレッドの数。
- 「スロークエリー/秒」（中と大） — スロークエリーの発生率。
- 「キャッシュヒット」（中と大） — サーバのキャッシュから返された読み取りの割合。
- 状態バッジ — 緑（アクティブでデータが新しい）、赤（直近のポーリングでサーバが応答しなくなった）、琥珀色（データをもう最新として示せない）。まだデータがないときはバッジ自体がありません：ウィジェットはサーバを選ぶよう求め、それ以外には何も主張しません。
- 接続バー — 意味を持つ色のバー：シアン（低い）、琥珀色（65%超）、赤（85%超）。

使えるサイズ：
- 小 — アクティブな接続とそのバー、サーバ名、状態バッジ。それだけです：数字がまるごと収まらなければならないサイズだからです。
- 中 — スループット、アクティブなスレッド、キャッシュヒット率（エンジンがキャッシュの数値を公開しない場合は代わりに稼働時間）が加わります。
- 大 — 上のすべてに、稼働時間と1秒あたりのスロークエリーが加わります。
- 特大 — 同じ内容を、本当の2列に並べます。iPadではホーム画面に置けます（iPhoneにはこのサイズがありません）。Macではデスクトップだけです。通知センターがこのサイズを受け付けないからです。
- ロック画面 — 長方形（iPhoneとiPad） — サーバ名、アクティブな接続数と最大数、QPS。
- ロック画面 — 円形（iPhoneとiPad） — 接続の使用率を示すリングで、中央に絶対数。
- ロック画面 — インライン（iPhoneとiPad） — 時計の横の1行で、アクティブな接続の数を表示します。

ウィジェットの追加方法：
- macOS：デスクトップを右クリックして「ウィジェットを編集」を選びます。*Calíope*を検索し、使いたいサイズをデスクトップか通知センターにドラッグします。
- iPhoneとiPad：アイコンが揺れ始めるまでホーム画面を長押しし、左上の「編集」、続いて「ウィジェットを追加」をタップし、*Calíope*を検索してサイズを選びます。

更新の頻度：
間隔はあなたが選び、ほかはすべてそこから決まります。「ダッシュボード」を開いているあいだは、その更新間隔の選択（1〜30秒）のペースでメトリクスが書き込まれます。ダッシュボードを閉じている場合は、「設定 › ウィジェット › バックグラウンドでウィジェットを更新」をオンにして、そこで間隔を選ぶ必要があります：30秒、1分、5分、15分。

バッジが琥珀色になるとき：
データがその間隔の3倍を超えて更新されなかったときで、下限は90秒です。間隔が5分ならウィジェットは15分間緑のままで、15分なら45分間です。上限は固定の数値ではなく設定から導かれます。更新が設定どおりにきちんと動いているのに琥珀色になるウィジェットは、何も警告していないからです。

そして、データが一度もなかった場合（サーバを選んでいないため）、ウィジェットは*データなし*とは言いません：サーバを選ぶよう求めます。

Apple Vision Pro：ウィジェットはホーム画面には置きません：壁に掛けるか（浮かせるか埋め込むか）、テーブルに置き、背景はガラスになります。システムの4つのサイズ（小、中、大、特大）があり、ロック画面の3つはiPhoneとiPadだけです。ウィジェットギャラリーから追加し、*Calíope*を検索して、ピンチして動かして置きます。

キーワード： ウィジェット、デスクトップ、ホーム画面、接続、QPS、稼働時間、キャッシュ、InnoDB、状態、バッジ、メトリクス、macOS、iPhone、iPad

1台のサーバではなくサーバ群全体を表示する2つ目のウィジェット：監視している台数、注意が必要な台数、最も悪い状態のサーバ。

場所： Widget › ウィジェット、ギャラリー、デスクトップ、ホーム画面

「メトリクス」ウィジェットは1台のサーバを見ます。こちらはすべてを見て、別の問いに答えます：見に行くべきものはあるか？

使える場所
- Mac、iPhone、iPad：Macのデスクトップと、iPhoneとiPadのホーム画面。
- Apple Vision Pro：壁かテーブルの上で、背景はガラスになります。

使えるサイズ：
- 小 — サーバ群の中で最も悪い状態と、監視しているサーバの数。
- 中 — リストで、最大3台、最も悪いものから順に。
- 大 — 同じリストで、最大6台。どちらでも、収まらない分は「ほかN台」と書かれ、アクセシビリティのサイズでは収まる行が少なくなります。

データの出どころ
- 同じアプリの「ヘルスモニタ」。ポーリングのたびに、結果をウィジェットが読むコンテナに書き込みます。
- ネットワークを通ることはなく、iCloudにも依存しません：ホーム画面に見えているものは、このデバイスで測定されたものです。
- iCloudへの公開がオフでも、ウィジェットは動き続けます。そのスイッチが決めるのはデバイスから出ていくものであって、あなた自身の画面に表示されるものではありません。

何も表示しないとき
- ヘルスモニタを一度開いてください：このデバイスではまだ何も測定されていません。
- 監視中のサーバはありません：モニタは動きましたが、そのリストに何もありません。

色だけが合図になることはありません：どの状態にも固有の形があり、VoiceOverの読み上げ順は、台数、最も悪いもの、注意が必要な台数を伝えます。

タップすると（Macではクリックすると）、ヘルスモニタが開きます。

キーワード： サーバ群、ウィジェット、ヘルス、モニタ、ホーム画面、サーバ、重大度

ウィジェットをタップまたはクリックするとCalíopeが開き、ピン留めしたサーバに自動で接続します。

場所： Widget › ディープリンク

「Calíopeウィジェットをタップまたはクリック」すると、アプリが開き、そのウィジェットが選んでいるサーバに直接接続して、対応するワークスペースの「ダッシュボード」に移動します。

仕組み：
- ウィジェットにはcaliope://server/<id>という形式の*ディープリンク*が含まれ、たまたま表示しているものではなく、そのウィジェットの設定で選ばれたサーバを指します。この違いが効くのは、まだメトリクスがないときです：ウィジェットは「サーバを選択」と表示していても、自分のサーバを開きます。
- アプリが開いていなければ、先に起動してからセッションを開きます。
- アプリがすでに開いていて、そのサーバのアクティブなセッションがあれば、それを前面に出すだけです。

どのサーバを開くか：
- ウィジェットを追加したときに選んだもの、またはあとで設定したもの：ウィジェットを長押し（iPad）または右クリック（Mac） →「Calíopeを編集」（iPadでは「ウィジェットを編集」） →「サーバ」。
- そのウィジェットでサーバが選ばれていなければ、表示しているデータのもとになっているサーバ、つまり最後にアクティブだったダッシュボードのサーバを開きます。
- 「設定 › ウィジェット」の「ピン留めしたプロファイル」は別物です：バックグラウンドで更新されるサーバであって、リンクが開くサーバではありません。

サーバが選ばれていなければ、ウィジェットはサーバを選ぶよう求めます。タップすると、Calíopeが接続マネージャの画面で開きます。

キーワード： ウィジェット、ディープリンク、タップ、クリック、開く、ピン留め、URLスキーム

ウィジェットはそれぞれ別のサーバを監視できます。追加するときに設定するか、あとで編集します。

場所： Widget › 設定

Calíopeウィジェットは設定できます：デスクトップやホーム画面に追加するとき、どのサーバを表示するかをシステムが尋ねます。画面に複数のウィジェットを同時に置き、それぞれ別のサーバ（本番環境、ステージング、レプリカなど）のメトリクスを表示できます。

ウィジェットを追加するときに設定する
- macOS：デスクトップを右クリックして「ウィジェットを編集」を選び、使いたい種類をデスクトップにドラッグします。ドロップしても選択画面は開きません：サーバはあとで、置いたウィジェットを右クリック →「Calíopeを編集」 →「サーバ」で選びます。
- iPad：ホーム画面を長押しし、「編集」 →「ウィジェットを追加」をタップし、Calíopeを検索してサイズを選びます。サーバはあとで、置いたウィジェットを長押し →「ウィジェットを編集」 →「サーバ」で選びます。

既存のウィジェットのサーバを変更する
- macOS：ウィジェットを右クリック →「Calíopeを編集」 →「サーバ」パラメータを変更します。
- iPad：ウィジェットを長押し →「ウィジェットを編集」 →「サーバ」パラメータを変更します。

App Groupで共有されるもの
- Calíopeは、アプリの起動時と、接続マネージャで変更を保存するたびに、プロファイルの最小限のカタログ（id、name、host）を公開します。ウィジェットはそのカタログを読んで選択肢を埋めます。入るのは、エンジンがメトリクスを公開できるプロファイルだけです（MongoDB、Redis、Apache Cassandra、ScyllaDBのものは提示されません。選ぶとウィジェットがずっと空のままになるからです）。パスワード、SSH鍵、証明書を見ることは決してありません。
- メトリクスはプロファイルごとに保存される（caliope_widget_metrics_<id>.json）ので、各ウィジェットは、アプリでどのセッションがアクティブかに関係なく、自分のデータを読みます。

サーバを設定していないウィジェット
- サーバを選ばなければ、ウィジェットはアプリで最後にアクティブだったサーバのメトリクスを表示します。しかし、選んでいて、そのサーバのメトリクスがまだない場合、ほかのサーバのものは表示しません：データがないと表示します。サーバにピン留めしたウィジェットが、別のサーバの名前や数値を表示することは決してありません。

キーワード： ウィジェット、設定、サーバを選択、AppIntent、複数サーバ、複数のウィジェット、選択、ウィジェットを編集、プロファイル

Calíopeがウィジェットの拡張機能とメトリクスを共有する仕組み。

場所： Calíope › 設定 › ウィジェット

Calíopeウィジェットは別の拡張機能の中にあり、メインのアプリのメモリーを読むことはできません。リアルタイムのデータを表示するために、アプリと拡張機能はApp Groupを通じて共通のコンテナを共有します。

識別子
- iPad：group.org.caliope.widget。
- macOS：同じものの前にチームIDを付けたもの（ASH9Q9BLUY.group.org.caliope.widget）。そこではシステムがその形式を求めるからです。

同じコンテナが、MacでもiOSでも、2つのウィジェット（メトリクスのものとサーバ群のヘルスのもの）にデータを供給します。iPhoneとiPadでは同じバイナリなので、同じApp Groupです。

共有されるもの
- 各サーバの最新のメトリクス（アクティブな接続、スループット（エンジンによってQPSかTPS）、稼働時間、スレッド、スロークエリー/秒、キャッシュヒット率）。
- 最後に更新したタイムスタンプと、書き込んだときの更新間隔。ウィジェットはこの2つを使って、いつバッジを琥珀色にするかを決めます：上限は更新間隔の3倍で、下限は90秒です。
- ピン留めしたプロファイルの識別子と、ディープリンク用のURL caliope://server/<id>。

更新の仕組み
- メインのアプリが開いて接続しているあいだ、WidgetDataStoreはポーリングのたびにApp Groupに書き込みます。
- 書き込んだあと、CalíopeはWidgetCenter.shared.reloadAllTimelines()を呼び、システムが与える次の機会にウィジェットが更新されるようにします。
- アプリを閉じると、ウィジェットはシステムが新しいタイムラインを求めるまで最後のデータを表示し続けます。更新間隔から導かれる上限を過ぎると、バッジは琥珀色になり、ラベルは*データなし*に変わります。

アプリの再インストールやApple IDの変更
- App GroupはデベロッパのチームIDに結びついています。Mac App StoreやApp StoreからCalíopeをインストールすると、macOSやiOSが自動でコンテナを作成します。設定は不要です。
- iPadを別のApple IDに移すと、コンテナはアプリとともに削除され、Calíopeを少なくとも一度開き直すまでウィジェットは空のままです。

言語はここを通りません。言語はシステムの設定でアプリケーションごとに選ぶもので、その選択は拡張機能にも届きます：ウィジェットは自分の言語を読み、誰も受け渡さなくてもアプリと同じ言語で表示します。

キーワード： App Group、ウィジェット、group.org.caliope.widget、WidgetDataStore、WidgetCenter、reloadAllTimelines、コンテナ、拡張機能、チームID、共有メトリクス

バッジが琥珀色でメトリクスが表示されないときの、段階的な診断。

場所： Widget › トラブルシューティング

Calíopeウィジェットに琥珀色のバッジと「データなし」のラベルが表示される場合、データが長すぎるあいだ更新されていないということです。「長すぎる」は固定の数値ではありません：書き込んだときの更新間隔の3倍で、下限は90秒です。

まず、ウィジェットが実際に何と表示しているかを見てください：
- 「サーバを選択」 — データが一度もありません。それが手順1です。
- 「データなし」 — データはありましたが、期限切れになりました。それ以外のすべてです。
- 赤の「オフライン」 — バックグラウンドの更新がポーリングしようとして、サーバが応答しませんでした。見えている数値は最後の正しいもので、だから薄く表示されています。

1. サーバが選ばれていますか？
- ウィジェットはそれぞれ自分のサーバを選びます：ウィジェットを長押し（iPad）または右クリック（Mac） → iPadでは「ウィジェットを編集」、Macでは「Calíopeを編集」 →「サーバ」。
- 何も選ばなければ、ウィジェットはアプリで最後にアクティブだったサーバに頼ります。それもなければ、表示するものがありません。

2. 誰がメトリクスを書き込んでいますか？
書き込むものは2つしかなく、どちらも動いていなければ、ウィジェットは当然止まったままです：
- そのサーバで開いている「ダッシュボード」。タブを閉じても数値は残ります：ウィジェットは最後の測定値を表示し続け、時期が来たら古いものとして示します。以前は閉じると削除されていたため、アプリを終了したまさにそのときに、すべてのウィジェットが空になっていました。
- 「設定 › ウィジェット」のバックグラウンドの更新。オンにして、*そのうえで*そこでピン留めするプロファイルを選ぶ必要があります。それが、アプリがバックグラウンドにあるあいだウィジェットを生かし続けるものです。

3. 間隔が長い場合は？
15分なら、ウィジェットは45分間緑のままで、そのあと、すべて動いていても琥珀色になります：2回の書き込みのあいだの時間が過ぎただけです。早めに琥珀色にしたい場合は、「設定 › ウィジェット」で間隔を短くしてください。

4. デバイスを再起動しましたか？
再起動のあとは、メインのアプリが少なくとも一度動くまで、ウィジェットには状態がありません。

5. システムが止めていませんか？
- iPadでは、Calíopeの「設定 › 一般 › Appのバックグラウンド更新」が有効になっている必要があります。そうでなければ、予定された更新が実行されません。
- Macには相当するものはありませんが、Calíopeを閉じているあいだに書き込むものもありません：ウィジェットは最後に受け取ったものを保ち、時期が来たら古いものとして示します。

6. どれにも当てはまらない場合
ウィジェットをデスクトップかホーム画面から取り除き、もう一度追加してください：システムにタイムラインを一から作り直させることになります。

キーワード： データなし、ウィジェット、琥珀色のバッジ、トラブルシューティング、解決、プロファイルをピン留め、バックグラウンド更新、キャッシュをリセット、診断