diff --git a/ja_JP/changes/all-changes-ee.md b/ja_JP/changes/all-changes-ee.md index 5fdfe1a9c..ef246b4fe 100644 --- a/ja_JP/changes/all-changes-ee.md +++ b/ja_JP/changes/all-changes-ee.md @@ -1,13 +1,15 @@ # EMQX Enterprise リリースノート -EMQX Enterprise のリリースノートページでは、各バージョンに含まれるアップデート、機能強化、および修正の詳細な記録を提供しています。 +EMQX Enterprise のリリースノートページでは、各バージョンに含まれる更新、強化、および修正の包括的かつ詳細な記録を提供しています。 ## v5.9 +- [5.9.1](./changes-ee-v5.md#_5-9-1): 2025-07-02 - [5.9.0](./changes-ee-v5.md#_5-9-0): 2025-05-02 ## v5.8 +- [5.8.7](./changes-ee-v5.md#_5-8-7): 2025-07-02 - [5.8.6](./changes-ee-v5.md#_5-8-6): 2025-03-25 - [5.8.5](./changes-ee-v5.md#_5-8-5): 2025-02-25 - [5.8.4](./changes-ee-v5.md#_5-8-4): 2024-12-26 diff --git a/ja_JP/changes/changes-ee-v5.md b/ja_JP/changes/changes-ee-v5.md index 1db1bbeff..d8dbeeeff 100644 --- a/ja_JP/changes/changes-ee-v5.md +++ b/ja_JP/changes/changes-ee-v5.md @@ -1,5 +1,77 @@ # EMQX Enterprise Version 5 +## 5.9.1 + +*Release Date: 2025-07-02* + +Make sure to check the breaking changes and known issues before upgrading to EMQX 5.9.1. + +### Enhancements + +- [#15364](https://github.com/emqx/emqx/pull/15364) Added support for custom HTTP headers in the OpenTelemetry gRPC (over HTTP/2) integration. This enhancement enables compatibility with collectors that require HTTP authentication. + +- [#15160](https://github.com/emqx/emqx/pull/15160) Added the `DELETE /mt/bulk_delete_ns` API for multi-tenancy management, which allows deleting namespaces in bulk. + +- [#15158](https://github.com/emqx/emqx/pull/15158) Added new `emqx ctl conf remove x.y.z` command, which removes the configuration key path `x.y.z` from the existing configuration. + +- [#15157](https://github.com/emqx/emqx/pull/15157) Added support for specifying private key file path for Snowflake Connector instead of using password. + + Users should either use password, private key, or neither (set parameters in `/etc/odbc.ini`). + +- [#15043](https://github.com/emqx/emqx/pull/15043) Instrument the DS Raft backend with basic metrics to provide insights into cluster status, database overview, shard replication, and replica transitions. + +### Bug Fixes + +#### Data Integration + +- [#15331](https://github.com/emqx/emqx/pull/15331) Fixed an issue in the InfluxDB action where line protocol conversion failed if the `timestamp` in `WriteSyntax` was left blank and no timestamp field was provided in the rule. + Now the system's current millisecond value is used instead, and millisecond precision is enforced. + +- [#15274](https://github.com/emqx/emqx/pull/15274) Improved the resilience of Postgres, Matrix, and TimescaleDB connectors by triggering a full reconnection on any health check failure. Previously, failed health checks could leave the connection in a broken state, causing operations to hang and potentially leading to out-of-memory issues. + +- [#15154](https://github.com/emqx/emqx/pull/15154) Fixed a rare race condition in Actions running in aggregated mode (e.g., S3, Azure Blob Storage, Snowflake) that could lead to a crash with errors like: + + ``` + ** Reason for termination == + ** {function_clause,[{emqx_connector_aggregator,handle_close_buffer,[...], ... + ``` + +- [#15147](https://github.com/emqx/emqx/pull/15147) Fixed an issue where some Actions failed to emit trace events during rule testing with simulated input data, even after request rendering. + + Affected Actions: + + - Couchbase + - Snowflake + - IoTDB (Thrift driver) + +- [#15383](https://github.com/emqx/emqx/pull/15383) Fixed a potential resource leak in the MQTT bridge. When the bridge failed to start, the topic index table was not properly cleaned up. This fix ensures that the index table is correctly deleted to prevent resource leaks. + +#### Smart Data Hub + +- [#15224](https://github.com/emqx/emqx/pull/15224) Fixed an issue where updating an External Schema Registry via the Dashboard would unintentionally overwrite the existing password with `******`. The password is now correctly preserved during updates. +- [#15190](https://github.com/emqx/emqx/pull/15190) Enhanced Message Transformation by allowing hard-coded values for QoS and topic. + +#### Observability + +- [#15299](https://github.com/emqx/emqx/pull/15299) Fixed a `badarg` error that occurred when exporting OpenTelemetry metrics. + +#### Telemetry + +- [#15216](https://github.com/emqx/emqx/pull/15216) Fixed a crash in the `emqx_telemetry` process that could occur when plugins were activated. + +#### Access Control + +- [#15184](https://github.com/emqx/emqx/pull/15184) Fixed the formatting of error messages returned when creating a blacklist fails. + +#### Clustering + +- [#15180](https://github.com/emqx/emqx/pull/15180) Reduced the risk of deadlocks during channel registration by fixing improper handling of `badrpc` errors in the `ekka_locker` module. These errors previously led to false positives in lock operations, potentially causing inconsistent cluster state and deadlocks. + +#### Security + + +- [#15159](https://github.com/emqx/emqx/pull/15159) Improved handling of Certificate Revocation List (CRL) Distribution Point URLs by stopping their refresh after repeated failures (default: 60 seconds). This prevents excessive error logs from unreachable URLs and improves overall system stability. + ## 5.9.0 *Release Date: 2025-05-02* @@ -118,7 +190,7 @@ Make sure to check the breaking changes and known issues before upgrading to EMQ - [#14892](https://github.com/emqx/emqx/pull/14892) Enhanced cluster load rebalancing: - Fixed load imbalance in core/replicant cluster. Previously, under certain conditions, all transactions from the replicants could be sent to a single core node. - + - Add CLI commands for rebalancing replicant nodes in relation to core nodes: - `emqx_ctl cluster core rebalance plan` @@ -434,6 +506,41 @@ Make sure to check the breaking changes and known issues before upgrading to EMQ - [#14775](https://github.com/emqx/emqx/pull/14775) QUIC Listener: Fixed issue where zone configurations are not applied after a config reload. +## 5.8.7 + +*Release Date: 2025-07-02* + +### Enhancements + +- [#15364](https://github.com/emqx/emqx/pull/15364) Added support for custom HTTP headers in the OpenTelemetry gRPC (over HTTP/2) integration. This enhancement enables compatibility with collectors that require HTTP authentication. + +### Bug Fixes + +- [#15383](https://github.com/emqx/emqx/pull/15383) Fixed a potential resource leak in the MQTT bridge. When the bridge failed to start, the topic index table was not properly cleaned up. This fix ensures that the index table is correctly deleted to prevent resource leaks. +- [#15331](https://github.com/emqx/emqx/pull/15331) Fixed an issue in the InfluxDB action where line protocol conversion failed if the `timestamp` in `WriteSyntax` was left blank and no timestamp field was provided in the rule. Now the system's current millisecond value is used instead, and millisecond precision is enforced. +- [#15274](https://github.com/emqx/emqx/pull/15274) Improved the resilience of Postgres, Matrix, and TimescaleDB connectors by triggering a full reconnection on any health check failure. Previously, failed health checks could leave the connection in a broken state, causing operations to hang and potentially leading to out-of-memory issues. +- [#15224](https://github.com/emqx/emqx/pull/15224) Fixed an issue where updating an External Schema Registry via the Dashboard would unintentionally overwrite the existing password with `******`. The password is now correctly preserved during updates. +- [#14989](https://github.com/emqx/emqx/pull/14989) Optimized the Kinesis Connector and Action to significantly reduce the number of AWS API calls during startup and health checks. This change helps prevent exceeding AWS Kinesis API rate limits (e.g., `ListStreams` and `DescribeStream`), which previously led to frequent health check failures when using larger connection pools or multiple connectors. +- [#15299](https://github.com/emqx/emqx/pull/15299) Fixed a `badarg` error that occurred when exporting OpenTelemetry metrics. + +## 5.8.7 + +*Release Date: 2025-07-02* + +### Enhancements + +- [#15364](https://github.com/emqx/emqx/pull/15364) Added support for custom HTTP headers in the OpenTelemetry gRPC (over HTTP/2) integration. This enhancement enables compatibility with collectors that require HTTP authentication. + +### Bug Fixes + +- [#15383](https://github.com/emqx/emqx/pull/15383) Fixed a potential resource leak in the MQTT bridge. When the bridge failed to start, the topic index table was not properly cleaned up. This fix ensures that the index table is correctly deleted to prevent resource leaks. +- [#15331](https://github.com/emqx/emqx/pull/15331) Fixed an issue in the InfluxDB action where line protocol conversion failed if the `timestamp` in `WriteSyntax` was left blank and no timestamp field was provided in the rule. + Now the system's current millisecond value is used instead, and millisecond precision is enforced. +- [#15274](https://github.com/emqx/emqx/pull/15274) Improved the resilience of Postgres, Matrix, and TimescaleDB connectors by triggering a full reconnection on any health check failure. Previously, failed health checks could leave the connection in a broken state, causing operations to hang and potentially leading to out-of-memory issues. +- [#15224](https://github.com/emqx/emqx/pull/15224) Fixed an issue where updating an External Schema Registry via the Dashboard would unintentionally overwrite the existing password with `******`. The password is now correctly preserved during updates. +- [#14989](https://github.com/emqx/emqx/pull/14989) Optimized the Kinesis Connector and Action to significantly reduce the number of AWS API calls during startup and health checks. This change helps prevent exceeding AWS Kinesis API rate limits (e.g., `ListStreams` and `DescribeStream`), which previously led to frequent health check failures when using larger connection pools or multiple connectors. +- [#15299](https://github.com/emqx/emqx/pull/15299) Fixed a `badarg` error that occurred when exporting OpenTelemetry metrics. + ## 5.8.6 *Release Date: 2025-03-25* diff --git a/ja_JP/dashboard/introduction.md b/ja_JP/dashboard/introduction.md index 191bbb194..413860f88 100644 --- a/ja_JP/dashboard/introduction.md +++ b/ja_JP/dashboard/introduction.md @@ -1,76 +1,115 @@ -# EMQX Dashboard +# EMQX ダッシュボード -EMQXは、EMQXクラスターの監視および管理を行い、必要な機能をウェブページ経由で設定できる組み込みのDashboard管理コンソールを提供します。新しいDashboardは刷新されたデザインを採用し、使いやすいMQTTブローカー管理UIを提供します。 +EMQX は、EMQX クラスターの監視および管理を行い、必要な機能をウェブページ経由で設定できる組み込みのダッシュボード管理コンソールを提供しています。新しいダッシュボードは刷新されたデザインを採用し、使いやすい MQTT ブローカー管理用 UI を提供します。 -EMQX Dashboardの新しいUI/UXデザインは、主要なデータやメトリクスの表示と内容を最適化し、視覚的な体験を向上させるとともに、接続、サブスクライブ、パブリッシュの認証・認可管理、データブリッジやルールエンジンを用いたデータ統合変換のサポートなど、より包括的で強力かつ使いやすい組み込み機能を提供します。ブラウザからの迅速かつ簡単なアクセスにより、ユーザーはより便利にEMQXを利用してIoTビジネスの開発を進められます。 +EMQX ダッシュボードの新しい UI/UX デザインは、主要なデータやメトリクスの表示と内容を最適化し、視覚的な体験を向上させるとともに、接続、サブスクライブ、パブリッシュの認証および認可管理、データブリッジやルールエンジンを用いたデータ統合変換のサポートなど、より包括的で強力かつ使いやすい組み込み機能を提供します。ブラウザからの迅速かつ簡単なアクセスにより、ユーザーはより便利に EMQX を利用して IoT ビジネスの開発を進められます。 ![image](./assets/dashboard_preview.png) ## 主な機能 -このセクションでは、Dashboardを通じて設定および管理可能なEMQXの各種機能を紹介します。 +このセクションでは、ダッシュボードを通じて設定および管理できる EMQX のさまざまな機能を紹介します。 -### [モニタリング](./monitoring.md) +### [監視](./monitoring.md) -稼働中のEMQXクラスターの全体情報を表示します。接続数、サブスクライブされたトピック、メッセージ配信数、インバウンド／アウトバウンドレートなどを含みます。また、ノード一覧、ノード情報、各種システムメトリクス情報も確認可能です。さらに、クライアント接続やサブスクリプションデータの閲覧・管理も行えます。 +稼働中の EMQX クラスターの全体情報を表示します。接続数、サブスクライブされたトピック、メッセージ配信数、インバウンドレート、アウトバウンドレートなどが含まれます。また、ノードリストやノード情報、各種システムメトリクス情報も確認できます。さらに、クライアント接続およびサブスクリプションデータの閲覧と管理も可能です。 ### [アクセス制御](./acloverview.md) -EMQXの認証および認可機構を視覚的に追加・設定できます。 +EMQX の認証および認可機構を視覚的に追加・設定できます。 ### [統合](./bridgeoverview.md) -強力なSQLベースのルールエンジンやデータ統合機能、またはFlowエディターのビジュアル機能を活用し、ローコードでのデータ処理と統合を実現します。これにより、MQTTデータのリアルタイム抽出、フィルタリング、強化、変換、保存、検証が可能です。 +強力な SQL ベースのルールエンジンとデータ統合、あるいは Flowデザイナーのビジュアル機能を活用し、ローコードでのデータ処理と統合を実現します。これにより、MQTT データのリアルタイム抽出、フィルタリング、エンリッチメント、変換、保存、検証が可能です。 ### 管理 #### クラスター設定 -MQTT、ログ、リスナーなどの設定項目をオンラインで変更・更新でき、更新成功後は即時反映されます。 +MQTT、ログ、リスナーなどの設定項目をオンラインで変更・更新でき、更新成功後すぐに反映されます。 -#### 高度なMQTT設定 +#### 高度な MQTT -トピック書き換え、自動サブスクライブ、遅延パブリッシュ、ファイル転送機能の管理と設定が可能です。 +トピック書き換え、自動サブスクライブ、遅延パブリッシュ、ファイル転送機能の管理と設定を行います。 #### 拡張機能 -カスタムプラグインの統合により、組み込みのゲートウェイ管理・設定を通じて接続プロトコルを拡張できます。また、Hooksを利用して関数呼び出しやメッセージ、モジュール間のイベント伝達をインターセプトし、システム機能を修正・拡張できます。 +カスタムプラグインを統合し、組み込みのゲートウェイ管理と設定を通じて接続プロトコルを拡張できます。また、Hooks を利用して関数呼び出し、メッセージ送受信、モジュール間イベントのインターセプトによりシステム機能を変更・拡張できます。 -### 問題分析と診断 +### 問題解析と診断 -オンラインのMQTT over WebSocketクライアント接続やトピックメトリクスによるデバッグに加え、スロウサブスクリプションやログトレースなどの機能を用いた診断や問題発見もサポートしています。 +オンライン MQTT over WebSocket クライアント接続やトピックメトリクスによるデバッグに加え、スロウサブスクリプションやログトレースなどの機能を使った診断や問題発見もサポートしています。 ### システム -ユーザーアカウント、監査ログ、APIキー、ライセンス設定、シングルサインオン機能の管理と設定が可能です。 +ユーザーアカウント、監査ログ、API キー、ライセンス設定、シングルサインオン機能の管理と設定を行います。 -## Dashboardの起動 +## ダッシュボードの起動 -EMQX Dashboardはウェブアプリケーションで、デフォルトでポート`18083`をリッスンします。EMQXを正常にインストール後、ブラウザで （非ローカル環境の場合はlocalhostを実際のIPアドレスに置き換えてください）にアクセスすることでDashboardを利用できます。 +EMQX ダッシュボードはウェブアプリケーションで、デフォルトでポート `18083` をリッスンします。EMQX を正常にインストールした後、ブラウザで （ローカル以外のマシンにデプロイしている場合は localhost を実際の IP アドレスに置き換えてください）にアクセスすることで EMQX ダッシュボードを利用できます。 ::: tip -Dashboardを有効にしなくてもEMQXは通常通り利用可能です。Dashboardはユーザーが視覚的に操作するためのオプション機能です。 +EMQX はダッシュボードを有効にしなくても通常通り使用可能です。ダッシュボードはあくまで視覚的に操作したいユーザー向けのオプションです。 ::: ### 初回ログイン -EMQXを初めてインストールしたユーザーは、Dashboardをブラウザで開いた後、デフォルトのユーザー名`admin`とパスワード`public`でログインできます。 +EMQX を初めてインストールしたユーザーは、ブラウザでダッシュボードを開いた後、デフォルトのユーザー名 `admin` とデフォルトのパスワード `public` を使ってログインできます。 -初回ログイン時、システムはデフォルトのユーザー名とパスワードでのログインを検出し、セキュリティ確保のためパスワードの変更を強制します。変更後のパスワードは元のパスワードと同一にできず、`public`の再利用は推奨されません。 +初回ログイン時に、システムはデフォルトのユーザー名とパスワードでログインしていることを自動検知し、ダッシュボードのセキュリティ向上のためパスワードの変更を強制します。変更後のパスワードは元のパスワードと同じにできません。また、`public` を再度ログインパスワードとして使うことは推奨されません。 -### パスワードのリセット +### URL を使ったトークンベースログイン -Dashboardのログインパスワードは`admins`コマンドでリセット可能です。詳細は[CLI - admins](../admin/cli.md#admins)をご覧ください。 +EMQX 5.6.0 以降、ダッシュボードは URL に認証情報を埋め込むことで直接ログインできるトークンベースのログイン方法をサポートしています。 + +この機能は、ユーザーが手動で認証情報を入力せずに自動的にログインできるシームレスなリダイレクトや統合シナリオに特に有効です。 + +#### このログイン方法の使い方 + +1. `/login` エンドポイントを使って認証トークンを取得します。レスポンスにはユーザー名が含まれないため、JSON ペイロードにユーザー名を手動で追加してからエンコードする必要があります。 + + 以下のように、トークンのリクエスト、ユーザー名の注入、Base64 エンコードを一括で実行できます。 + + ``` + curl -s -X POST "http://127.0.0.1:18083/api/v5/login" \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{"username": "admin","password": "public"}' | jq '.username = "admin"' | base64 + ``` + +2. ログイン URL を構築します。ダッシュボードの URL の `login_meta` クエリパラメータにエンコード済み文字列を埋め込みます。 + + EMQX 5.6.0 より前のバージョンの場合： + + ```bash + http://localhost:18083?login_meta=BASE64_ENCODED_STRING + ``` + + これにより、デフォルトのクラスター概要ページにリダイレクトされます。 + + EMQX 5.6.0 以降の場合： + + ```bash + http://localhost:18083/#/dashboard/overview?login_meta=BASE64_ENCODED_STRING + ``` + + ログイン後の遷移先ページを指定できます。 + +この方法により、事前認証されたスムーズなユーザー体験で EMQX ダッシュボードにアクセスできます。トークンは安全に取り扱い、有効期限や権限範囲を適切に設定してください。 + +### パスワードリセット + +ダッシュボードのログインパスワードは `admins` コマンドを使ってリセットできます。詳細は [CLI - admins](../admin/cli.md#admins) を参照してください。 ```bash ./bin/emqx ctl admins passwd ``` -### パスワードの有効期限 +### パスワード有効期限 -現在のDashboardログインパスワードの使用期間が設定された有効期限（`password_expired_time`）を超えると、ログイン時にパスワード更新を促されます。`password_expired_time`設定の詳細は[Dashboard設定](../configuration/dashboard.md)を参照してください。 +現在のダッシュボードログインパスワードの使用期間が設定されたパスワード有効期限（`password_expired_time`）を超えると、ログイン時にパスワード更新を促されます。`password_expired_time` の設定詳細は [ダッシュボード設定](../configuration/dashboard.md) をご覧ください。 -「管理者」ロールのユーザーは[REST API](../admin/api.md)を使ってパスワード有効期限を設定することも可能です。 +「管理者」ロールを持つユーザーは、[REST API](../admin/api.md) を使ってパスワード有効期限を設定することも可能です。 **例**: @@ -82,16 +121,16 @@ curl -X 'PUT' \ -d '{"password_expired_time": "1d"}' ``` -この例では、パスワード有効期限を1日に設定しています。 +この例では、パスワード有効期限を 1 日に設定しています。 ### アカウントロックと解除 -セキュリティ強化のため、EMQX Dashboardは「アカウントロックと解除」機能を実装しています。ユーザーが5分間に5回パスワードを誤入力すると、そのアカウントは10分間ロックされます。 +セキュリティ強化のため、EMQX ダッシュボードは「アカウントロックと解除」機能を実装しています。ユーザーが 5 分間にパスワードを 5 回間違えると、アカウントは 10 分間ロックされます。 -「管理者」ロールのユーザーはCLIからユーザーのパスワードをリセットすることで手動でアカウントを解除できます。10分経過後は自動的にロックが解除され、通常通りログイン可能になります。 +「管理者」ロールを持つユーザーは CLI を使ってユーザーのパスワードをリセットすることで手動でアカウントロックを解除できます。10 分経過すると自動的にロックが解除され、通常通りログイン可能になります。 -管理者はバックエンド設定を通じてロック時間やロック発動までの失敗回数も設定可能です。詳細は[Dashboard設定](../configuration/dashboard.md)をご覧ください。 +管理者はロック時間やロックに必要な失敗回数をバックエンド設定で変更可能です。設定の詳細は [ダッシュボード設定](../configuration/dashboard.md) を参照してください。 -## Dashboardの設定 +## ダッシュボードの設定 -DashboardはデフォルトでHTTPをリッスンし、ポート番号は18083です。ユーザーはHTTPSを有効化したり、リスナーポートを変更したりできます。Dashboard設定の詳細な変更方法については、[EMQX Enterprise設定マニュアル](https://docs.emqx.com/en/enterprise/v@EE_VERSION@/hocon/)を参照してください。 +ダッシュボードはデフォルトで HTTP をリッスンし、ポート番号は 18083 です。ユーザーは HTTPS を有効化したり、リスナーポートを変更したりできます。ダッシュボードの設定方法や変更方法の詳細は [EMQX Enterprise 設定マニュアル](https://docs.emqx.com/en/enterprise/v@EE_VERSION@/hocon/) をご参照ください。 diff --git a/ja_JP/data-integration/data-bridge-rocketmq.md b/ja_JP/data-integration/data-bridge-rocketmq.md index 2cc7db057..d9c92a780 100644 --- a/ja_JP/data-integration/data-bridge-rocketmq.md +++ b/ja_JP/data-integration/data-bridge-rocketmq.md @@ -2,51 +2,51 @@ EMQXは[RocketMQ](https://rocketmq.apache.org/)へのデータブリッジをサポートしており、MQTTメッセージやクライアントイベントをRocketMQに転送できます。例えば、RocketMQを使ってデバイスからのセンサーデータやログデータを収集することが可能です。 -本ページでは、EMQXとRocketMQ間のデータ連携の詳細な概要と、データ連携の作成および検証に関する実践的な手順を提供します。 +本ページでは、EMQXとRocketMQ間のデータ統合の詳細な概要と、データ統合の作成および検証に関する実践的な手順を提供します。 ::: tip 注意 -Alibaba CloudがホストするRocketMQサービスを利用する場合、このデータ連携はバッチモードをサポートしていません。 +Alibaba CloudがホストするRocketMQサービスを利用する場合、本データ統合はバッチモードをサポートしていません。 ::: -## 動作原理 +## 動作概要 -RocketMQデータ連携は、EMQXに標準搭載された機能であり、EMQXのリアルタイムデータキャプチャと送信機能をRocketMQの強力なメッセージキュー処理機能と組み合わせています。組み込みの[ルールエンジン](./rules.md)コンポーネントにより、EMQXからRocketMQへのデータ取り込みが簡素化され、複雑なコーディングが不要になります。 +RocketMQデータ統合はEMQXに標準搭載された機能であり、EMQXのリアルタイムデータキャプチャと送信機能とRocketMQの強力なメッセージキュー処理機能を組み合わせています。組み込みの[ルールエンジン](./rules.md)コンポーネントにより、EMQXからRocketMQへのデータ取り込みが簡素化され、複雑なコーディングを不要にします。 -以下の図は、EMQXとRocketMQ間の典型的なデータ連携アーキテクチャを示しています。 +以下の図は、EMQXとRocketMQ間のデータ統合の典型的なアーキテクチャを示しています。 ![EMQX Integration RocketMQ](./assets/emqx-integration-rocketmq.png) -MQTTデータをRocketMQに取り込む流れは次の通りです： +MQTTデータをRocketMQに取り込む流れは以下の通りです。 -1. **メッセージのパブリッシュと受信**：産業用IoTデバイスはMQTTプロトコルを通じてEMQXに正常に接続し、リアルタイムMQTTデータをEMQXにパブリッシュします。EMQXがこれらのメッセージを受信すると、ルールエンジン内でマッチング処理を開始します。 -2. **メッセージデータの処理**：メッセージが到着するとルールエンジンを通過し、EMQXで定義されたルールによって処理されます。ルールは事前定義された条件に基づき、RocketMQにルーティングすべきメッセージを判別します。ペイロードの変換が指定されている場合は、データ形式の変換、特定情報のフィルタリング、追加コンテキストによるペイロードの強化などが適用されます。 -3. **RocketMQへのデータ取り込み**：ルールによる処理が完了したメッセージは、RocketMQへの転送アクションがトリガーされます。処理済みデータはシームレスにRocketMQに書き込まれます。 -4. **データの保存と活用**：データがRocketMQに保存された後、企業はそのクエリ機能を活用して様々なユースケースに対応できます。例えば金融業界では、RocketMQを信頼性の高い高性能メッセージキューとして利用し、決済端末や取引システムからのデータを管理します。これにより、リスク管理、不正検知・防止、規制遵守などの要件を満たすためのデータ分析や規制プラットフォームと連携可能です。 +1. **メッセージのパブリッシュと受信**：産業用IoTデバイスはMQTTプロトコルを通じてEMQXに正常に接続し、リアルタイムのMQTTデータをEMQXにパブリッシュします。EMQXがこれらのメッセージを受信すると、ルールエンジン内でマッチング処理が開始されます。 +2. **メッセージデータの処理**：メッセージが到着するとルールエンジンを通過し、EMQXで定義されたルールによって処理されます。ルールは事前定義された条件に基づき、どのメッセージをRocketMQにルーティングするかを決定します。ペイロード変換が指定されている場合は、データ形式の変換、特定情報のフィルタリング、追加コンテキストによるペイロードの強化などが適用されます。 +3. **RocketMQへのデータ取り込み**：ルールによる処理が完了すると、メッセージをRocketMQに転送するアクションがトリガーされます。処理済みデータはシームレスにRocketMQに書き込まれます。 +4. **データの保存と活用**：データがRocketMQに保存されることで、企業はそのクエリ機能を活用して様々なユースケースに対応できます。例えば金融業界では、RocketMQを信頼性の高い高性能メッセージキューとして利用し、決済端末や取引システムからのデータを管理します。メッセージをデータ分析や規制プラットフォームに連携させ、リスク管理、不正検知・防止、規制遵守などの要件を満たします。 -## 特長と利点 +## 特長とメリット -RocketMQとのデータ連携は、以下の特長と利点をビジネスにもたらします： +RocketMQとのデータ統合は、以下の特長と利点をビジネスにもたらします。 -- **信頼性の高いIoTデータメッセージ配信**：EMQXはMQTTメッセージを信頼性高くバッチ送信でき、IoTデバイスとRocketMQおよびアプリケーションシステムの統合を実現します。 -- **MQTTメッセージの変換**：ルールエンジンを活用し、EMQXはMQTTメッセージの抽出、フィルタリング、強化、変換を行い、RocketMQに送信します。 -- **クラウドネイティブな弾力的スケーリング**：EMQXとRocketMQは共にクラウドネイティブアーキテクチャで構築されており、Kubernetes（K8s）をはじめとしたクラウドネイティブエコシステムとの親和性が高く、ビジネスの急速な成長に対応する無限の弾力的スケールが可能です。 -- **柔軟なトピックマッピング**：RocketMQデータ連携はMQTTトピックとRocketMQトピックの柔軟なマッピングをサポートし、RocketMQメッセージ内のキー（Key）や値（Value）の設定を簡単に行えます。 -- **高スループットシナリオでの処理能力**：RocketMQデータ連携は同期・非同期の両書き込みモードをサポートし、シナリオに応じてレイテンシとスループットのバランスを柔軟に調整可能です。 +- **信頼性の高いIoTデータメッセージ配信**：EMQXはMQTTメッセージを確実にバッチ送信でき、IoTデバイスとRocketMQおよびアプリケーションシステムの統合を実現します。 +- **MQTTメッセージの変換**：ルールエンジンを使い、EMQXはMQTTメッセージのフィルタリングや変換を行えます。データ抽出、フィルタリング、強化、変換を経てRocketMQに送信可能です。 +- **クラウドネイティブな弾力的スケーリング**：EMQXとRocketMQはともにクラウドネイティブアーキテクチャ上に構築されており、Kubernetes（K8s）に対応しクラウドネイティブエコシステムと統合可能です。ビジネスの急速な成長に合わせて無限かつ弾力的にスケールできます。 +- **柔軟なトピックマッピング**：RocketMQデータ統合はMQTTトピックとRocketMQトピックの柔軟なマッピングをサポートし、RocketMQメッセージ内のキー（Key）や値（Value）の設定を簡単に行えます。 +- **高スループットシナリオでの処理能力**：RocketMQデータ統合は同期・非同期の書き込みモードをサポートし、シナリオに応じてレイテンシとスループットのバランスを柔軟に調整可能です。 ## はじめる前に -このセクションでは、RocketMQデータ連携を作成する前に必要な準備とRocketMQサーバーのセットアップ方法を説明します。 +本節では、RocketMQデータ統合の作成を始める前に必要な準備とRocketMQサーバーのセットアップ方法について説明します。 ### 前提条件 -- EMQXデータ連携の[ルール](./rules.md)に関する知識 -- [データ連携](./data-bridges.md)に関する知識 +- EMQXデータ統合の[ルール](./rules.md)に関する知識 +- [データ統合](./data-bridges.md)に関する知識 ### RocketMQのインストール -1. RocketMQをセットアップするためのdocker-composeファイル`rocketmq.yaml`を準備します。 +1. RocketMQをセットアップするためのdocker-composeファイル`rocketmq.yaml`を用意します。 ```yaml version: '3.9' @@ -81,7 +81,7 @@ services: - mqnamesrv ``` -2. RocketMQの実行に必要なフォルダと設定を作成します。 +2. RocketMQの実行に必要なフォルダと設定を準備します。 ```bash mkdir rocketmq @@ -131,38 +131,38 @@ docker run --rm -e NAMESRV_ADDR=host.docker.internal:9876 apache/rocketmq:4.9.4 ::: tip -Linux環境では、`host.docker.internal`を実際のIPアドレスに変更してください。 +Linux環境では`host.docker.internal`を実際のIPアドレスに変更してください。 ::: ## コネクターの作成 -このセクションでは、SinkをRocketMQサーバーに接続するためのコネクター作成方法を説明します。 +本節では、SinkをRocketMQサーバーに接続するためのコネクター作成方法を示します。 -以下の手順は、EMQXとRocketMQをローカルマシンで実行している場合を想定しています。リモートで実行している場合は設定を適宜調整してください。 +以下の手順はEMQXとRocketMQをローカルマシンで実行していることを前提としています。リモート環境の場合は設定を適宜調整してください。 1. EMQXダッシュボードに入り、**Integration** -> **Connectors**をクリックします。 2. ページ右上の**Create**をクリックします。 3. **Create Connector**ページで**RocketMQ**を選択し、**Next**をクリックします。 -4. **Configuration**ステップで以下を設定します： - - **Connector name**：コネクター名を入力します。英数字の組み合わせで、例：`my_rocketmq` - - **Servers**：`127.0.0.1:9876`を入力 - - **Namespace**：RocketMQサービスにネームスペースが設定されていなければ空欄のまま。 - - **AccessKey**、**SecretKey**、**Secret Token**：サービス構成に応じて空欄または入力 - - その他はデフォルトのまま -5. 詳細設定（任意）：[Sinkの機能](./data-bridges.md#features-of-sink)を参照 -6. **Create**をクリックする前に、**Test Connectivity**でRocketMQサーバーへの接続確認が可能です。 -7. ページ下部の**Create**ボタンをクリックしてコネクター作成を完了します。ポップアップで**Back to Connector List**か**Create Rule**を選択可能です。ルール作成については、[メッセージ保存用RocketMQ Sinkのルール作成](#create-a-rule-with-rocketmq-sink-for-message-storage)および[イベント記録用RocketMQ Sinkのルール作成](#create-a-rule-with-rocketmq-sink-for-events-recording)を参照してください。 +4. **Configuration**ステップで以下を設定します。 + - **Connector name**：コネクター名を英数字で入力します（例：`my_rocketmq`）。 + - **Servers**：`127.0.0.1:9876`を入力します。 + - **Namespace**：RocketMQサービスにネームスペースが設定されていない限り空欄のままにします。 + - **AccessKey**、**SecretKey**、**Secret Token**：RocketMQサービスの設定に応じて空欄のままか入力します。 + - その他はデフォルトのままにします。 +5. 高度な設定（任意）：詳細は[Sinkの特長](./data-bridges.md#features-of-sink)を参照してください。 +6. **Create**をクリックする前に、**Test Connectivity**をクリックしてコネクターがRocketMQサーバーに接続できるか確認できます。 +7. ページ下部の**Create**ボタンをクリックしてコネクター作成を完了します。ポップアップダイアログで**Back to Connector List**をクリックするか、**Create Rule**をクリックしてSinkを使ったルール作成に進めます。詳細は[メッセージ保存用RocketMQ Sinkのルール作成](#create-a-rule-with-rocketmq-sink-for-message-storage)および[イベント記録用RocketMQ Sinkのルール作成](#create-a-rule-with-rocketmq-sink-for-events-recording)を参照してください。 ## メッセージ保存用RocketMQ Sinkのルール作成 -このセクションでは、ダッシュボードでソースMQTTトピック`t/#`のメッセージを処理し、処理済みデータを設定済みのSink経由でRocketMQトピック`TopicTest`に転送するルールの作成方法を説明します。 +本節では、ダッシュボードでMQTTソーストピック`t/#`のメッセージを処理し、処理済みデータを設定済みSink経由でRocketMQトピック`TopicTest`に転送するルールの作成方法を示します。 1. EMQXダッシュボードで**Integration** -> **Rules**をクリックします。 2. ページ右上の**Create**をクリックします。 -3. ルールIDに`my_rule`を入力します。メッセージ保存用ルールのSQL文は以下の通りです。これはトピック`t/#`配下のMQTTメッセージをRocketMQに保存することを意味します。 +3. ルールIDに`my_rule`と入力します。メッセージ保存用ルールとして、以下のSQL文を**SQL Editor**に入力します。これはトピック`t/#`配下のMQTTメッセージをRocketMQに保存することを意味します。 注意：独自のSQL文を指定する場合は、Sinkが必要とするすべてのフィールドを`SELECT`句に含めてください。 @@ -175,49 +175,49 @@ Linux環境では、`host.docker.internal`を実際のIPアドレスに変更し ::: tip - 初心者の方は**SQL Examples**や**Enable Test**を使ってSQLルールの学習とテストが可能です。 + 初心者の方は**SQL Examples**や**Enable Test**をクリックしてSQLルールを学習・テストしてください。 ::: -4. + **Add Action**ボタンをクリックし、ルールでトリガーされるアクションを定義します。このアクションによりEMQXはルールで処理したデータをRocketMQに送信します。 +4. + **Add Action**ボタンをクリックし、ルールによりトリガーされるアクションを定義します。このアクションによりEMQXはルールで処理したデータをRocketMQに送信します。 -5. **Type of Action**ドロップダウンから`RocketMQ`を選択します。**Action**はデフォルトの`Create Action`のままにします。既存のSinkがあれば選択可能ですが、ここでは新規Sinkを作成します。 +5. **Type of Action**ドロップダウンリストから`RocketMQ`を選択します。**Action**はデフォルトの`Create Action`のままにします。既存のSinkがあれば選択可能ですが、本例では新規Sinkを作成します。 -6. Sinkの名前を入力します。英数字の組み合わせで指定してください。 +6. Sink名を英数字で入力します。 -7. **Connector**ドロップダウンから先に作成した`my_rocketmq`を選択します。新規コネクターはドロップダウン横のボタンで作成可能です。設定パラメータは[コネクターの作成](#create-a-connector)を参照してください。 +7. **Connector**ドロップダウンから先に作成した`my_rocketmq`を選択します。新規コネクターはドロップダウン横のボタンから作成可能です。設定パラメータは[コネクターの作成](#create-a-connector)を参照してください。 -8. **RocketMQ Topic**欄に`TopicTest`を入力します。 +8. **RocketMQ Topic**欄に`TopicTest`と入力します。 9. **Template**はデフォルトで空欄のままにします。 ::: tip - 空欄の場合、メッセージ全体がRocketMQに転送されます。実際にはJSONテンプレートデータです。 + 空欄の場合、メッセージ全体がRocketMQに転送されます。実際の値はJSONテンプレートデータです。 ::: -10. **Fallback Actions（任意）**：メッセージ配信失敗時の信頼性向上のため、1つ以上のフォールバックアクションを定義できます。詳細は[Fallback Actions](./data-bridges.md#fallback-actions)を参照してください。 +10. **Fallback Actions（任意）**：メッセージ配信失敗時の信頼性向上のため、1つ以上のフォールバックアクションを定義可能です。詳細は[フォールバックアクション](./data-bridges.md#fallback-actions)を参照してください。 -11. **詳細設定（任意）**：[Sinkの機能](./data-bridges.md#features-of-sink)を参照してください。 +11. **高度な設定（任意）**：詳細は[Sinkの特長](./data-bridges.md#features-of-sink)を参照してください。 -12. **Create**をクリックする前に、**Test Connectivity**でSinkがRocketMQサーバーに接続できるか確認できます。 +12. **Create**をクリックする前に、**Test Connectivity**でSinkがRocketMQサーバーに接続可能かテストできます。 -13. **Create**ボタンをクリックし、Sink設定を完了します。新しいSinkが**Action Outputs**に追加されます。 +13. **Create**ボタンをクリックしてSink設定を完了します。新しいSinkが**Action Outputs**に追加されます。 -14. **Create Rule**ページに戻り、設定内容を確認後、**Create**ボタンをクリックしてルールを生成します。 +14. **Create Rule**ページに戻り、設定内容を確認して**Create**をクリックしルールを生成します。 -これでRocketMQ Sink用のルール作成が完了しました。**Integration** -> **Rules**ページで新規作成したルールを確認できます。**Actions(Sink)**タブをクリックすると新しいRocketMQ Sinkが表示されます。 +これでRocketMQ Sink用のルール作成が完了しました。**Integration** -> **Rules**ページで新規ルールを確認できます。**Actions(Sink)**タブをクリックすると新しいRocketMQ Sinkが表示されます。 -また、**Integration** -> **Flow Designer**でトポロジーを確認すると、トピック`t/#`配下のメッセージがルール`my_rule`で解析され、RocketMQに送信・保存されていることがわかります。 +また、**Integration** -> **Flow Designer**をクリックするとトポロジーが表示され、トピック`t/#`のメッセージがルール`my_rule`で解析されてRocketMQに送信・保存されていることを確認できます。 ## イベント記録用RocketMQ Sinkのルール作成 -このセクションでは、クライアントのオンライン／オフライン状態を記録し、イベントデータを設定済みSink経由でRocketMQトピック`TestTopic`に転送するルールの作成方法を説明します。 +本節では、クライアントのオンライン／オフライン状態を記録し、イベントデータを設定済みSink経由でRocketMQトピック`TestTopic`に転送するルールの作成方法を示します。 -ルール作成手順は[メッセージ保存用RocketMQ Sinkのルール作成](#create-a-rule-with-rocketmq-sink-for-message-storage)とほぼ同様ですが、SQLルールの文法が異なります。 +ルール作成手順は[メッセージ保存用RocketMQ Sinkのルール作成](#create-a-rule-with-rocketmq-sink-for-message-storage)とほぼ同様ですが、SQLルール文が異なります。 -オンライン／オフライン状態記録用のSQLルール文は以下の通りです： +オンライン／オフライン状態記録用のSQLルール文は以下の通りです。 ```sql SELECT @@ -228,7 +228,7 @@ FROM ::: tip -便宜上、オンライン／オフラインイベントの受信用に`TopicTest`トピックを再利用します。 +便宜上、オンライン／オフラインイベント受信用に`TopicTest`トピックを再利用します。 ::: @@ -240,11 +240,11 @@ MQTTXを使ってトピック`t/1`にメッセージを送信し、オンライ mqttx pub -i emqx_c -t t/1 -m '{ "msg": "hello RocketMQ" }' ``` -Sinkの稼働状況を確認すると、新規の受信メッセージと送信メッセージが1件ずつあるはずです。 +Sinkの稼働状況を確認すると、新規の受信メッセージと送信メッセージが1件ずつ増えているはずです。 データが`TopicTest`トピックに転送されているか確認してください。 -以下のようなデータがコンシューマーに表示されます。 +以下のデータがコンシューマーにより出力されます。 ```bash ConsumeMessageThread_please_rename_unique_group_name_4_1 Receive New Messages: [MessageExt [brokerName=broker-a, queueId=3, storeSize=581, queueOffset=0, sysFlag=0, bornTimestamp=1679037578889, bornHost=/172.26.83.106:43920, storeTimestamp=1679037578891, storeHost=/172.26.83.106:10911, msgId=AC1A536A00002A9F000000000000060E, commitLogOffset=1550, bodyCRC=7414108, reconsumeTimes=0, preparedTransactionOffset=0, toString()=Message{topic='TopicTest', flag=0, properties={MIN_OFFSET=0, MAX_OFFSET=8, CONSUME_START_TIME=1679037605342, CLUSTER=DefaultCluster}, body=[...], transactionId='null'}]] diff --git a/ja_JP/data-integration/rule-sql-builtin-functions.md b/ja_JP/data-integration/rule-sql-builtin-functions.md index 49dea3120..75ebf1351 100644 --- a/ja_JP/data-integration/rule-sql-builtin-functions.md +++ b/ja_JP/data-integration/rule-sql-builtin-functions.md @@ -1,6 +1,6 @@ # 組み込みSQL関数 -ルールエンジンは多様な組み込み関数を提供しています。これらの関数はSQL内で利用でき、基本的なデータ処理を実現します。主なカテゴリは以下の通りです： +ルールエンジンは多様な組み込み関数を提供しています。これらの関数はSQL内で利用可能で、基本的なデータ処理を実現できます。以下のカテゴリがあります： - [数学関数](#mathematical-functions) - [データ型判定関数](#data-type-judgment-functions) @@ -18,30 +18,30 @@ - [システム関数](#system-function) - [条件関数](#conditional-functions) -本節では、すべての関数宣言は以下の形式に準拠しています： +本節の関数宣言はすべて以下の形式に準拠しています： ```bash FuncName(Arg 1: Type 1 | ..., ...) -> Type 1 | ... ``` -例えば、`abs(X: integer | float) -> integer | float` は、引数 `X` のデータ型が整数または浮動小数点数であり、戻り値の型もそれに対応することを意味します。 +例えば、`abs(X: integer | float) -> integer | float` は、引数 `X` のデータ型が整数または浮動小数点数であり、戻り値もそれに対応して整数または浮動小数点数となることを示します。 -指定された引数が範囲外であったり、サポートされていないデータ型を使用した場合、現在のSQL実行は失敗し、失敗回数が1増加しますのでご注意ください。 +引数が指定範囲を超えたり、サポートされていないデータ型が使われた場合、現在のSQL実行は失敗し、失敗回数が1増加しますのでご注意ください。 :::tip -1. 一部のエスケープシーケンスは使用時にアンエスケープが必要です。詳細は [unescape関数](#unescapestring-string---string) を参照してください。 -2. EMQX 5.0以降、複雑なデータ変換に [jq構文](https://stedolan.github.io/jq/manual/) を利用可能です。詳細は [jq関数](./rule-sql-jq.md) をご覧ください。 +1. 一部のエスケープシーケンスは使用時にアンエスケープが必要です。詳細は[unescape関数](#unescapestring-string---string)を参照してください。 +2. EMQX 5.0以降、複雑なデータ変換に[jq構文](https://stedolan.github.io/jq/manual/)もサポートしています。詳細は[jq関数](./rule-sql-jq.md)をご覧ください。 ::: ## 数学関数 -EMQXは幅広い数学関数をサポートしています： +EMQXは以下の幅広い数学関数をサポートしています： -- 三角関数および双曲線関数：sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh -- 数値関数：abs, ceil, floor, round, sqrt, fmod -- 指数関数および対数関数：exp, power, log, log10, log2 +- 三角関数・双曲線関数：sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh +- 数値関数：abs, ceil, floor, round, sqrt, fmod +- 指数・対数関数：exp, power, log, log10, log2 ### abs(X: integer | float) -> integer | float @@ -134,7 +134,7 @@ exp(1) = 2.718281828459045 ### floor(X: integer | float) -> integer -`X` 以下の最大の整数を返します。例： +`X` 以下の最大の整数に切り捨てます。例： ```bash floor(3.6) = 3 @@ -150,7 +150,7 @@ fmod(6.5, 2.5) = 1.5 ### log(X: integer | float) -> float -`X` の自然対数を返します。`X` は0より大きい必要があります。例： +`X` の自然対数を返します。`X` は0より大きくなければなりません。例： ```bash log(7.38905609893065) = 2.0 @@ -158,7 +158,7 @@ log(7.38905609893065) = 2.0 ### log10(X: integer | float) -> float -`X` の底10の対数を返します。`X` は0より大きい必要があります。例： +`X` の底10の対数を返します。`X` は0より大きくなければなりません。例： ```bash log10(100) = 2.0 @@ -166,7 +166,7 @@ log10(100) = 2.0 ### log2(X: integer | float) -> float -`X` の底2の対数を返します。`X` は0より大きい必要があります。例： +`X` の底2の対数を返します。`X` は0より大きくなければなりません。例： ```bash log2(8) = 3.0 @@ -239,11 +239,11 @@ tanh(0.5) = 0.46211715726000974 ## データ型判定関数 -指定したフィールドのデータ型を判定し、指定したデータ型に合致するかどうかを真偽値で返します。 +指定したフィールドのデータ型を判定し、指定のデータ型に合致するかどうかを真偽値で返します。 ### is_array(Term: any) -> boolean -`Term` が配列型か判定します。例： +`Term` が配列型かどうか判定します。例： ```bash is_array([1, 2]) = true @@ -255,7 +255,7 @@ is_array('[1, 2]') = false ### is_bool(Term: any) -> boolean -`Term` がブール型か判定します。例： +`Term` がブール型かどうか判定します。例： ```bash is_bool(true) = true @@ -265,7 +265,7 @@ is_bool('true') = false ### is_float(Term: any) -> boolean -`Term` が浮動小数点型か判定します。例： +`Term` が浮動小数点型かどうか判定します。例： ```bash is_float(123.4) = true @@ -274,7 +274,7 @@ is_float(123) = false ### is_int(Term: any) -> boolean -`Term` が整数型か判定します。例： +`Term` が整数型かどうか判定します。例： ```bash is_int(123) = true @@ -283,7 +283,7 @@ is_int(123.4) = false ### is_map(Term: any) -> boolean -`Term` がマップ型か判定します。例： +`Term` がマップ型かどうか判定します。例： ```bash is_map(json_decode('{"value": 1}')) = true @@ -292,8 +292,7 @@ is_map(json_decode('[{"value": 1}]')) = false ### is_null(Term: any) -> boolean -変数 `Term` が未定義か判定します。 -この関数は変数に値が割り当てられているかを判定するために使い、値がJSONの `null` であっても未定義とはみなしません。 +変数 `Term` が未定義かどうか判定します。この関数は変数に値が割り当てられているかを判定しますが、その値がJSONの `null` である場合は含みません。 例： @@ -305,7 +304,7 @@ is_null(map_get('b', json_decode('{"b": null}'))) = false ### is_null_var(Term: any) -> boolean -変数 `Term` が未定義または `null` か判定します。例： +変数 `Term` が未定義または `null` かどうか判定します。例： ```sql is_null_var(this_is_an_unassigned_variable) = true @@ -315,11 +314,11 @@ is_null_var(map_get('b', json_decode('{"b": null}'))) = true ### is_not_null_var(Term: any) -> boolean -`is_null_var` の逆で、変数 `Term` が定義されておりかつ `null` でないか判定します。 +`is_null_var` の逆で、変数 `Term` が定義されており、かつ `null` でないか判定します。 ### is_num(Term: any) -> boolean -`Term` が整数または浮動小数点型か判定します。例： +`Term` が整数型または浮動小数点型かどうか判定します。例： ```bash is_num(123) = true @@ -329,7 +328,7 @@ is_num('123') = false ### is_str(Term: any) -> boolean -`Term` が文字列型か判定します。例： +`Term` が文字列型かどうか判定します。例： ```bash is_str('123') = true @@ -338,7 +337,7 @@ is_str(123) = false ### is_empty(Array or Map) -> boolean -配列またはマップが空か判定します。例： +配列またはマップが空かどうか判定します。例： ```bash is_empty(json_decode('{}')) = true @@ -352,7 +351,7 @@ is_empty(map_get('key', '{"key" : [1}')) = false ### bool(Term: boolean | integer | string) -> boolean -`Term` をブール型に変換します。`Term` はブール型、整数型の0または1、文字列型のtrueまたはfalseのみ許容されます。 +`Term` をブール型に変換します。`Term` はブール型、整数型の0または1、文字列型の `true` または `false` のみ有効です。 例： @@ -362,7 +361,7 @@ bool(true) = true bool(0) = false bool('false') = false -# 誤り例 +# 間違い例 bool(20) bool('True') ``` @@ -371,7 +370,7 @@ bool('True') `Term` を浮動小数点数に変換します。 -`Term` が文字列の場合、科学的記数法が利用可能です（例：`float('3.14e4')`）。浮動小数点数は最大16桁の有効数字をサポートします。文字列で表現された浮動小数点数の有効数字が16桁を超える場合、変換時に丸め誤差が発生する可能性があります。 +`Term` が文字列の場合、科学的記数法も使用可能です（例：`float('3.14e4')`）。浮動小数点数は最大16桁の有効数字をサポートします。文字列で表現された浮動小数点数の有効数字が16桁を超えると、変換時に丸め誤差が発生する可能性があります。 例： @@ -384,14 +383,14 @@ float('3.14e+4') = 31400 float('3.14e-4') = 0.000314 float('3.14E-4') = 0.000314 -# 有効数字が16桁を超えると丸め誤差により異なる入力が同じ出力になる場合があります。 +# 有効数字が16桁を超えると丸め誤差により異なる入力が同じ出力になることがある float('0.12345678901234566') = 0.12345678901234566 float('0.12345678901234567') = 0.12345678901234566 ``` ### float(Term: float | integer | string, Decimals: integer) -> float -`Term` を小数点以下最大 `Decimals` 桁の浮動小数点数に変換します。`Decimals` の範囲は `(0, 253]` です。その他の動作は `float/1` と同様です。例： +`Term` を小数点以下最大 `Decimals` 桁の浮動小数点数に変換します。`Decimals` の範囲は `(0, 253]` です。その他の動作は `float/1` と同じです。例： ```bash float('3.1415926', 3) = 3.142 @@ -402,7 +401,7 @@ float('0.000012345', 5) = 0.00001 浮動小数点数 `Float` を文字列に変換します。小数点以下最大 `Decimals` 桁まで含み、末尾のゼロは切り捨てられます。`Decimals` の範囲は `[0, 253]` です。`Float` の有効数字が16桁を超える場合、変換時に丸め誤差が発生する可能性があります。 -浮動小数点数はコンピュータ上で正確に保存できないため、`Decimals` が `Float` の小数点以下の桁数（先行ゼロ含む）を超える場合、`float2str` は `Float` の2進近似値の10進表現を返すことがあります。 +浮動小数点数はコンピュータ上で正確に格納できないため、`Decimals` が `Float` の小数点以下桁数（先行ゼロ含む）より大きい場合、`float2str` は `Float` の2進近似の10進表現を返すことがあります。 例： @@ -412,10 +411,10 @@ float2str(0.1, 20) = '0.10000000000000000555' float2str(0.1, 25) = '0.1000000000000000055511151' float2str(0.00000000001, 20) = '0.00000000001' -# 末尾のゼロは切り捨てられます +# 末尾のゼロは切り捨てられる float2str(0.100001, 5) = '0.1' -# 有効数字が16桁を超えると丸め誤差により異なる入力が同じ出力になる場合があります。 +# 有効数字が16桁を超えると丸め誤差により異なる入力が同じ出力になることがある float2str(123456789.01234565, 8) = '123456789.01234566' float2str(123456789.01234566, 8) = '123456789.01234566' ``` @@ -424,9 +423,9 @@ float2str(123456789.01234566, 8) = '123456789.01234566' `Term` を整数に変換します。 -- `Term` がブール型の場合、trueは1、falseは0に変換されます。 -- `Term` が浮動小数点型の場合、`Term` 以下の最大の整数に切り捨てられます。 -- `Term` が文字列の場合、少なくとも1つの数字を含み、先頭に `+` または `-` の1文字の接頭辞が付くことができ、先行ゼロは無視されます。数学的表記もサポートします。 +- `Term` がブール型の場合、`true` は1、`false` は0に変換されます。 +- `Term` が浮動小数点型の場合、`Term` 以下の最大の整数に切り捨てられます。 +- `Term` が文字列の場合、少なくとも1つの数字を含み、先頭に単一の `+` または `-` が付くことができ、先行ゼロは無視されます。数学的表記もサポートされます。 - `Term` が整数の場合、そのまま返されます。 例： @@ -442,7 +441,7 @@ int('0010') = 10 int('3.1415e2') = 314 int(substr('Number 100', 7)) = 100 -# 誤り例 +# 間違い例 int('-100+200') int('Number 100') ``` @@ -451,8 +450,8 @@ int('Number 100') 任意の型の `Term` を文字列に変換します。 -- `Term` がマップまたは配列の場合、`str` 関数は `Term` をJSONエンコードしようとします。 -- `Term` が浮動小数点数の場合、末尾のゼロを切り捨てた対応する文字列を返します。戻り値の文字列は小数点以下最大10桁まで保持します。より多くの小数桁を返すには `float2str` 関数を使用してください。 +- `Term` がマップまたは配列の場合、`str` 関数は `Term` をJSONエンコードしようとします。 +- `Term` が浮動小数点数の場合、末尾のゼロを切り捨てた対応する文字列を返します。返される文字列は小数点以下最大10桁まで保持します。より多くの小数桁を返すには `float2str` 関数を使用してください。 例： @@ -462,12 +461,13 @@ str(nth(1, json_decode('[false]'))) = 'false' str(json_decode({"msg": "hello"})) = '{"msg":"hello"}' str(json_decode('[{"msg": "hello"}]')) = '[{"msg":"hello"}]' -# 末尾のゼロは切り捨てられます -# 小数点以下最大10桁を保持 +# 末尾のゼロは切り捨てられる +# 小数点以下最大10桁まで保持 str(0.30000000040) = '0.3000000004' str(0.30000000004) = '0.3' -# 小数点以下10桁で丸められます +# 小数点以下10桁で丸められる +# 10桁目以降で丸め str(3.14159265359) = '3.1415926536' str(0.000000314159265359) = '0.0000003142' ``` @@ -476,7 +476,7 @@ str(0.000000314159265359) = '0.0000003142' 任意の `Term` をUTF-8エンコードされた文字列に変換します。 -動作は `str(Any)` と同一です。 +動作は `str(Any)` と同様です。 ```bash str_utf8(100) = '100' @@ -484,29 +484,31 @@ str_utf8(nth(1, json_decode('[false]'))) = 'false' str_utf8(json_decode({"msg": "hello"})) = '{"msg":"hello"}' str_utf8(json_decode('[{"msg": "hello"}]')) = '[{"msg":"hello"}]' -# 末尾のゼロは切り捨てられます -# 小数点以下最大10桁を保持 +# 末尾のゼロは切り捨てられる +# 小数点以下最大10桁まで保持 str_utf8(0.30000000040) = '0.3000000004' str_utf8(0.30000000004) = '0.3' -# 小数点以下10桁で丸められます +# 小数点以下10桁で丸められる +# 10桁目以降で丸め str_utf8(3.14159265359) = '3.1415926536' str_utf8(0.000000314159265359) = '0.0000003142' ``` ### str_utf16_le(Term: any) -> binary -任意の `Term` をUTF-16リトルエンディアンでエンコードされたバイナリ文字列に変換します。 +任意の `Term` をUTF-16リトルエンディアンエンコードされたバイナリ文字列に変換します。 ::: tip -UTF-16リトルエンディアンエンコード文字列はJSONオブジェクト内で正しく表示されない場合があります。EMQXでは通常バイナリデータとして扱われます。可読な16進文字列に変換するには `bin2hexstr` 関数を使用してください。 -このエンコードはMicrosoft SQL Serverなど、リトルエンディアンUTF-16を利用するシステムで一般的に使用されます。 +UTF-16リトルエンディアンエンコード文字列はJSONオブジェクト内で正しく表示されない場合があります。EMQXでは通常バイナリデータとして扱われます。可読な16進数文字列に変換するには `bin2hexstr` 関数を使用してください。 + +このエンコードはMicrosoft SQL ServerのようなリトルエンディアンUTF-16を使用するシステムで一般的に使われます。 ::: ```bash -# Unicodeの 'h' の例: +# Unicodeの `h`： # | h(\u68) | # | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 0 | 1 | 0 | 0 | 0 | (ビッグエンディアン) # | 0x00 | 0x68 | @@ -519,11 +521,11 @@ bin2hexstr(str_utf16_le('hello')) = '680065006C006C006F00' ## 文字列操作関数 -文字列の大文字・小文字変換、空白削除、部分文字列抽出、置換、エスケープ・アンエスケープなどに利用できます。 +文字列の大文字・小文字変換、空白削除、部分文字列抽出、置換、エスケープ／アンエスケープなどに利用できます。 ### ascii(Char: string) -> integer -文字 `Char` のASCIIコードを返します。`Char` に複数文字が含まれる場合、最初の1文字のコードのみ返します。例： +文字 `Char` のASCIIコードを返します。`Char` に複数文字が含まれる場合は最初の1文字のコードのみ返します。例： ```bash ascii('a') = 97 @@ -540,7 +542,7 @@ concat('Name:', 'John') = 'Name:John' ### find(String: string, SearchPattern: string) -> string -`String` 内で部分文字列 `SearchPattern` を検索し、`SearchPattern` より前の部分を削除して残りを返します。`SearchPattern` が見つからない場合は空文字列を返します。`find(String, SearchPattern, 'leading')` と同等です。 +`String` 内で部分文字列 `SearchPattern` を検索し、`SearchPattern` より前の部分を削除して残りを返します。`SearchPattern` が見つからなければ空文字列を返します。`find(String, SearchPattern)` は `find(String, SearchPattern, 'leading')` と同等です。 例： @@ -551,9 +553,7 @@ find('..., Value: 1.2', 'Data') = '' ### find(String: string, SearchPattern: string, Direction: string) -> string -`find/2` と同様ですが、`Direction` で検索方向を指定できます。 - -例： +`find/2` と同様ですが、`Direction` で検索方向を指定できます。例： ```bash find('Front, Middle, End', ', ', 'leading') = ', Middle, End' @@ -578,7 +578,7 @@ lower('Hello') = 'hello' ### ltrim(String: string) -> string -`trim/1` と同様ですが、文字列の先頭の空白文字のみを削除します。例： +`trim/1` と同様ですが、先頭の空白文字のみ削除します。例： ```bash ltrim('\t hello \n') = 'hello \n' @@ -587,7 +587,7 @@ ltrim('\t hello \r\n') = 'hello \r\n' ### pad(String: string, Length: integer) -> string -`String` の末尾に空白を追加して指定長さ `Length` にパディングします。例： +`String` の末尾に空白を追加し、指定した長さ `Length` にします。例： ```bash pad('hello', 8) = 'hello ' @@ -595,9 +595,9 @@ pad('hello', 8) = 'hello ' ### pad(String: string, Length: integer, Direction: string) -> string -`pad/2` と同様ですが、`Direction` でパディング方向を指定できます。 -`leading` は先頭に空白を埋め、`trailing` は末尾に空白を埋め、`both` は両端に空白を埋めます。 -`both` 指定時、埋める空白数が奇数の場合は末尾に多く埋めます。 +`pad/2` と同様ですが、`Direction` でパディング方向を指定できます。`leading` は先頭に空白を追加、`trailing` は末尾に空白を追加、`both` は両端に空白を追加します。 + +`both` 指定時、追加する空白数が奇数の場合は最後の空白が末尾に追加されます。 例： @@ -609,9 +609,9 @@ pad('hello', 8, 'both') = ' hello ' ### pad(String: string, Length: integer, Direction: string, Char: string) -> string -`pad/3` と同様ですが、指定したグラフェムクラスタ `Char` でパディングします。 +`pad/3` と同様ですが、指定したグラフェムクラスター `Char` でパディングします。 -ルールエンジンは `Char` が合法なグラフェムクラスタかをチェックしないため、`Char` が複数文字でも1文字分として扱われます。例： +ルールエンジンは `Char` が合法なグラフェムクラスターかどうかをチェックしないため、`Char` の文字数に関わらず1文字として扱われます。例： ```bash pad('hello', 8, 'trailing', '!') = 'hello!!!' @@ -630,7 +630,7 @@ regex_match('a23', '^\d+$') = false ### regex_replace(String: string, Expression: string, Replacement: string) -> string -文字列 `String` の正規表現 `Expression` にマッチする部分を `Replacement` に置換します。マッチがなければ元の文字列を返します。例： +文字列 `String` の正規表現 `Expression` にマッチする部分を `Replacement` で置換します。マッチがなければ元の文字列を返します。例： ```bash regex_replace('hello 123', '\d+', 'world') = 'hello world' @@ -645,7 +645,9 @@ regex_replace('a;b; c', ';\s*', ',') = 'a,b,c' ::: -正規表現のキャプチャグループを用いて文字列から部分抽出を行います。完全一致部分は除き、キャプチャされたグループのリストを返します。マッチしない場合やグループがない場合は空リストを返します。 +正規表現のキャプチャグループを用いて文字列から部分抽出を行います。完全一致部分は除外されます。 + +マッチがあればすべてのキャプチャグループのリストを返し、マッチなしまたはグループなしの場合は空リストを返します。 例： @@ -658,7 +660,7 @@ regex_extract('Date: 2021-05-20', '(\d{4})-(\d{2})-(\d{2})') -> ['2021', '05', ' ### replace(String: string, SearchPattern: string, Replacement: string) -> string -文字列 `String` のすべての `SearchPattern` を `Replacement` に置換します。例： +`String` 内のすべての `SearchPattern` を `Replacement` に置換します。例： ```bash replace('ab..cd..ef', '..', '**') = 'ab**cd**ef' @@ -671,8 +673,8 @@ replace('ab..cd..ef', '..', '') = 'abcdef' `Where` の値は以下の通りです： -- `all`: すべての `SearchPattern` を置換（`replace/3` と同等） -- `leading`: 先頭の `SearchPattern` のみ置換 +- `all`: すべての `SearchPattern` を置換（`replace/3` と同等） +- `leading`: 先頭の `SearchPattern` のみ置換 - `trailing`: 末尾の `SearchPattern` のみ置換 例： @@ -702,7 +704,7 @@ rm_prefix('foo/bar', 'xxx/') = 'foo/bar' ### rtrim(String: string) -> string -`trim/1` と同様ですが、文字列の末尾の空白文字のみを削除します。例： +`trim/1` と同様ですが、末尾の空白文字のみ削除します。例： ```bash rtrim('\t hello \n') = '\t hello' @@ -713,9 +715,9 @@ rtrim('\t hello \r\n') = '\t hello' `String` を区切り文字 `Separator` で分割し、部分文字列の配列を返します。 -2つ以上の連続した区切り文字は1つとして扱われません。`split/2` は出力結果のトリムと空文字列の除外をデフォルトで行います。空文字列を残したい場合は `split(String, Separator, 'notrim')` を使用してください。 +隣接する複数の区切り文字は1つとして扱われず、空文字列が結果に含まれる場合があります。`split/2` はデフォルトで結果をトリムし、空文字列を除外します。空文字列を残したい場合は `split(String, Separator, 'notrim')` を使います。 -`Separator` は複数文字でも構いませんが、全体として扱われます。複数の区切り文字を同時に指定したい場合は `tokens` 関数を使用してください。 +`Separator` は複数文字でも可能ですが、全体で1つの区切り文字として扱われます。複数の区切り文字を指定したい場合は `tokens` 関数を使ってください。 例： @@ -724,21 +726,21 @@ split('a;', ';') = ['a'] split('a;b;c', ';') = ['a', 'b', 'c'] split('a;;b;;c', ';') = ['a', 'b', 'c'] -# Howell Wise の前の空白に注意 +# Howell Wise の前のスペースに注意 split('Sienna Blake; Howell Wise', ';') = ['Sienna Blake', ' Howell Wise'] split('Sienna Blake; Howell Wise', '; ') = ['Sienna Blake', 'Howell Wise'] ``` ### split(String: string, Separator: string, Option: string) -> array -`split/2` と同様ですが、`Option` で処理する区切り文字の位置や空文字列の返却有無を指定できます。 +`split/2` と同様ですが、`Option` で処理する区切り文字の位置や空文字列の扱いを指定できます。 `Option` の値は以下の通りです： -- `notrim`: 文字列内のすべての区切り文字を処理し、空文字列を含む可能性あり -- `leading`: 先頭の区切り文字のみ処理し、空文字列は含まない -- `leading_notrim`: 先頭の区切り文字のみ処理し、空文字列を含む可能性あり -- `trailing`: 末尾の区切り文字のみ処理し、空文字列は含まない +- `notrim`: 文字列中のすべての区切り文字を処理し、空文字列を含む可能性あり +- `leading`: 先頭の区切り文字のみ処理し、空文字列は含まない +- `leading_notrim`: 先頭の区切り文字のみ処理し、空文字列を含む可能性あり +- `trailing`: 末尾の区切り文字のみ処理し、空文字列は含まない - `trailing_notrim`: 末尾の区切り文字のみ処理し、空文字列を含む可能性あり 例： @@ -753,11 +755,11 @@ split('a;b;c;', ';', 'trailing_notrim') = ['a;b;c', ''] ### sprintf(Format, ...) -> string -`Format` に従ってフォーマットされた文字列を返します。`Format` 文字列は通常の文字とフォーマット用制御シーケンスを含みます。 +`Format` に従ってフォーマットされた文字列を返します。`Format` 文字列は通常文字とフォーマット制御シーケンスを含みます。 制御シーケンスの形式は一般的に `~F.P.PadModC` です。 -`C` は制御シーケンスの種類を示し必須です。`F`, `P`, `Pad`, `Mod` は任意です。詳細は https://www.erlang.org/doc/man/io.html#fwrite-1 を参照してください。 +`C` は制御シーケンスのタイプを決定し、必須です。`F`, `P`, `Pad`, `Mod` はすべて省略可能です。詳細は https://www.erlang.org/doc/man/io.html#fwrite-1 を参照してください。 例： @@ -768,7 +770,7 @@ sprintf('count: ~p~n', 100) = 'count: 100\n' ### strlen(String: string) -> integer -文字列 `String` の長さを返します。例： +`String` の長さを返します。例： ```bash strlen('hello') = 5 @@ -777,7 +779,7 @@ strlen('hello\n') = 6 ### substr(String: string, Start: integer) -> string -文字列 `String` の位置 `Start` から末尾までの部分文字列を返します。文字列の添字は0始まりです。例： +`String` の `Start` 位置（0始まり）から末尾までの部分文字列を返します。例： ```bash substr('hello', 0) = 'hello' @@ -786,7 +788,7 @@ substr('hello world', 6) = 'world' ### substr(String: string, Start: integer, Length: integer) -> string -文字列 `String` の位置 `Start` から最大長 `Length` の部分文字列を返します。添字は0始まりです。例： +`String` の `Start` 位置（0始まり）から最大 `Length` 文字の部分文字列を返します。例： ```bash substr('hello world!', 6, 5) = 'world' @@ -796,7 +798,7 @@ substr('hello world!', 6, 5) = 'world' `String` を `SeparatorList` に含まれる文字で分割し、部分文字列のリストを返します。 -2つ以上の連続した区切り文字は1つとして扱われ、空文字列は発生しません。 +隣接する複数の区切り文字は1つとして扱われ、空文字列は発生しません。 例： @@ -815,7 +817,7 @@ tokens('a\rb\nc\r\nd', ';', 'nocrlf') = ['a', 'b', 'c', 'd'] ### trim(String: string) -> string -文字列 `String` の先頭と末尾から空白文字（スペース、タブ、改ページ、改行など）を削除します。`\r\n` はUnicodeのグラフェムクラスタとして扱われるため、まとめて削除されます。例： +`String` の先頭と末尾から空白文字（スペース、タブ、フォームフィード、改行など）を削除します。`\r\n` はUnicodeのグラフェムクラスターとしてまとめて削除されます。例： ```bash trim('\t hello \n') = 'hello' @@ -824,7 +826,7 @@ trim('\t hello \r\n') = 'hello' ### unescape(String: string) -> string -エスケープシーケンスを元の文字に戻します。SQL内でエスケープシーケンスを使う場合は、この関数でアンエスケープしてから処理してください。 +エスケープシーケンスを元の文字に戻します。SQLでエスケープシーケンスを使う場合は、この関数でアンエスケープしてから処理してください。 ::: tip @@ -847,7 +849,7 @@ my-device SELECT split(payload, '\n') as device_info FROM 't/#' ``` -出力結果： +結果： ```json { @@ -863,7 +865,7 @@ SELECT split(payload, '\n') as device_info FROM 't/#' SELECT split(payload, unescape('\n')) as device_info FROM 't/#' ``` -出力結果： +結果： ```json { @@ -880,27 +882,27 @@ SELECT split(payload, unescape('\n')) as device_info FROM 't/#' - 標準Cエスケープシーケンス： - - `\n`：改行（LF） - - `\t`：水平タブ（HT） - - `\r`：復帰（CR） - - `\b`：バックスペース（BS） - - `\f`：改ページ（FF） - - `\v`：垂直タブ（VT） - - `\'`：シングルクォート（'） - - `\"`：ダブルクォート（"） - - `\\`：バックスラッシュ（\） - - `\?`：疑問符（?） - - `\a`：アラート（ベル、BEL） + - `\n`（改行 LF） + - `\t`（水平タブ HT） + - `\r`（復帰 CR） + - `\b`（バックスペース BS） + - `\f`（フォームフィード FF） + - `\v`（垂直タブ VT） + - `\'`（シングルクォート '） + - `\"`（ダブルクォート "） + - `\\`（バックスラッシュ \） + - `\?`（疑問符 ?） + - `\a`（アラートベル BEL） - 16進エスケープコード： - - `\xH...`：`H...` は1文字以上の16進数（0-9, A-F, a-f）で、任意のUTF-32文字をエンコード可能。 + - `\xH...`（`H...` は1つ以上の16進数字 0-9, A-F, a-f）、任意のutf32文字をエンコード可能 -認識できないエスケープシーケンスや無効なUnicode文字の場合は例外が発生します。 +認識できないエスケープシーケンスや不正なUnicode文字の場合は例外をスローします。 ### upper(String: string) -> string -文字列 `String` の小文字を大文字に変換します。例： +`String` の小文字を大文字に変換します。例： ```bash upper('hello') = 'Hello' @@ -910,7 +912,7 @@ upper('hello') = 'Hello' ### map_get(Key: string, Map: map) -> any -`Map` の指定した `Key` の値を返します。`Key` が存在しない場合は `undefined` を返します。例： +`Map` 内の指定した `Key` の値を返します。`Key` が存在しない場合は `undefined` を返します。例： ```bash map_get('msg', json_decode('{"msg": "hello"}')) = 'hello' @@ -928,7 +930,7 @@ map_get('value', json_decode('{"data": [1.2, 1.3]}'), []) = [] ### map_keys(Map: map) -> array -`Map` のすべてのキーの配列を返します。例： +`Map` のすべてのキーを配列で返します。例： ```bash map_keys(json_decode('{"a": 1, "b": 2}')) = ['a', 'b'] @@ -936,7 +938,7 @@ map_keys(json_decode('{"a": 1, "b": 2}')) = ['a', 'b'] ### map_put(Key: string, Value: any, Map: map) -> map -`Map` に `Key` と対応する `Value` を挿入し、更新されたマップを返します。`Key` が既に存在する場合は値を上書きします。例： +`Map` に `Key` と対応する `Value` を挿入し、更新後のマップを返します。`Key` が既に存在する場合は値を上書きします。例： ```bash map_get('b', map_put('b', 1, json_decode('{"a": 1}'))) = 1 @@ -951,9 +953,9 @@ map_get('a', map_put('a', 2, json_decode('{"a": 1}'))) = 2 ::: -マップをRedisの `HSET`（または `HMSET`）コマンド用のフィールド名と値のリストに変換します。 +`Map` をRedisの `HSET`（または `HMSET`）コマンドのフィールド名と値のリストに変換します。 -例：`SELECT map_to_redis_hset_args(payload.value) as hset_fields FROM t/1` のように使用し、`hset_fields` をRedisアクションのテンプレート `HMSET name1 ${hset_fields}` に組み込みます。 +例：`SELECT map_to_redis_hset_args(payload.value) as hset_fields FROM t/1` のように使い、Redisアクションのテンプレートで `HMSET name1 ${hset_fields}` として利用可能です。 例えば、`payload.value` が `{"a" : 1, "b": 2}` の場合、コマンドは `HMSET name1 b 2 a 1` のようになります。マップのフィールド順序は非決定的です。 @@ -967,7 +969,7 @@ map_to_entries(json_decode('{"a": 1, "b": 2}')) = [{"key": "a", "value": 1},{"ke ### map_values(Map: map) -> array -`Map` のすべての値の配列を返します。例： +`Map` のすべての値を配列で返します。例： ```bash map_values(json_decode('{"a": 1, "b": 2}')) = [1, 2] @@ -975,7 +977,7 @@ map_values(json_decode('{"a": 1, "b": 2}')) = [1, 2] ### mget(Key: string | array, Map: map) -> any -`Map` の指定した `Key` の値を返します。`Key` が存在しない場合は `undefined` を返します。配列で複数キーを指定すると、ネストしたマップから対応する値を取得します。例： +`Map` 内の指定した `Key` の値を返します。`Key` が存在しない場合は `undefined` を返します。配列で複数キーを指定すると、ネストされたマップから対応する値を取得できます。例： ```bash mget('c', json_decode('{"a": {"b": 1}}')) = undefined @@ -985,7 +987,7 @@ mget(['a', 'b'], json_decode('{"a": {"b": 1}}')) = 1 ### mput(Key: string | array, Value: any, Map: map) -> map -`Map` に `Key` と対応する `Value` を挿入し、更新されたマップを返します。`Key` が既に存在する場合は値を上書きします。配列で複数キーを指定すると、ネストしたマップにデータを挿入します。例： +`Map` に `Key` と対応する `Value` を挿入し、更新後のマップを返します。`Key` が既に存在する場合は値を上書きします。配列で複数キーを指定すると、ネストされたマップにデータを挿入できます。例： ```bash mget(['a', 'b'], mput(['a', 'b'], 2, json_decode('{"a": {"b": 1}}'))) = 2 @@ -1005,7 +1007,7 @@ map_size(json_decode('{"msg": "hello"}')) = 1 ### contains(Item: any, Array: array) -> boolean -配列 `Array` に指定した `Item` が含まれるか判定します。例： +配列 `Array` が指定した `Item` を含むか判定します。例： ```bash contains(2, [1, 2, 3]) = true @@ -1023,7 +1025,7 @@ contains(json_decode('{"a": 1}'), [json_decode('{"a": 1}'), json_decode('{"b": 2 # 正しい例 first(['John', 'David']) = 'John' -# 誤り例 +# 間違い例 first([]) ``` @@ -1035,7 +1037,7 @@ first([]) # 正しい例 last(['John', 'David']) = 'David' -# 誤り例 +# 間違い例 last([]) ``` @@ -1056,14 +1058,14 @@ length([]) = 0 # 正しい例 nth(1, [1,2,3]) = 1 -# 誤り例 +# 間違い例 nth(0, [1,2,3]) nth(4, [1,2,3]) ``` ### sublist(Length: integer, Array: array) -> any -配列 `Array` の先頭から最大長 `Length` の部分配列を返します。`Length` が配列長を超える場合は全配列を返します。例： +配列 `Array` の先頭から最大 `Length` 要素の部分配列を返します。`Length` が配列長を超える場合は全体を返します。例： ```bash sublist(3, [1,2,3,4]) = [1,2,3] @@ -1072,7 +1074,7 @@ sublist(10, [1,2,3,4]) = [1,2,3,4] ### sublist(Start: integer, Length: integer, Array:array) -> any -`sublist/2` と同様ですが、`Start` で返す開始要素を指定できます。`Start` + `Length` が配列長を超える場合は全配列を返します。例： +`sublist/2` と同様ですが、`Start` で開始位置を指定できます。`Start` + `Length` が配列長を超える場合は全体を返します。例： ```bash sublist(2, 10, [1,2,3,4]) = [2,3,4] @@ -1082,7 +1084,7 @@ sublist(2, 10, [1,2,3,4]) = [2,3,4] ### md5(String: string) -> string -任意長の文字列 `String` に対し、128ビット長のMD5ハッシュ値を計算します。ハッシュ値は32桁の16進数文字列で返され、小文字（a〜f）固定です。 +任意長の文字列 `String` の128ビット固定長MD5ハッシュ値を計算します。ハッシュ値は32桁の16進数文字列で返され、小文字（a〜f）固定です。 例： @@ -1092,7 +1094,7 @@ md5('hello') = '5d41402abc4b2a76b9719d911017c592' ### sha(String: string) -> string -任意長の文字列 `String` に対し、160ビット長のSHA-1ハッシュ値を計算します。ハッシュ値は40桁の16進数文字列で返され、小文字（a〜f）固定です。 +任意長の文字列 `String` の160ビット固定長SHA-1ハッシュ値を計算します。ハッシュ値は40桁の16進数文字列で返され、小文字（a〜f）固定です。 例： @@ -1102,7 +1104,7 @@ sha('hello') = 'aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d' ### sha256(String: string) -> string -任意長の文字列 `String` に対し、256ビット長のSHA-2ハッシュ値を計算します。ハッシュ値は64桁の16進数文字列で返され、小文字（a〜f）固定です。 +任意長の文字列 `String` の256ビット固定長SHA-2ハッシュ値を計算します。ハッシュ値は64桁の16進数文字列で返され、小文字（a〜f）固定です。 例： @@ -1112,7 +1114,7 @@ sha256('hello') = '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9 ## 圧縮・解凍関数 -注意：バイナリデータは直接JSONエンコードできません。`bin2hexstr` 関数で16進文字列に変換してください。 +注意：バイナリデータはJSONエンコードできないため、`bin2hexstr` 関数で16進数文字列に変換してください。 ### gunzip(Data: binary) -> binary | string @@ -1124,7 +1126,7 @@ gunzip(hexstr2bin('1F8B0800000000000013CB48CDC9C9070086A6103605000000')) = 'hell ### gzip(Data: binary | string) -> binary -DEFLATEアルゴリズムで `Data` を圧縮し、gzヘッダーと末尾のチェックサムを含む圧縮結果を返します。例： +DEFLATEアルゴリズムで `Data` を圧縮し、gzヘッダーと末尾のチェックサムを含む結果を返します。例： ```bash bin2hexstr(gzip('hello')) = '1F8B0800000000000013CB48CDC9C9070086A6103605000000' @@ -1140,7 +1142,7 @@ unzip(hexstr2bin('CB48CDC9C90700')) = 'hello' ### zip(Data: binary | string) -> binary -DEFLATEアルゴリズムで `Data` を圧縮し、zlibヘッダーと末尾のチェックサムを含まない圧縮結果を返します。例： +DEFLATEアルゴリズムで `Data` を圧縮し、zlibヘッダーと末尾のチェックサムを含まない結果を返します。例： ```bash bin2hexstr(zip('hello')) = 'CB48CDC9C90700' @@ -1148,7 +1150,7 @@ bin2hexstr(zip('hello')) = 'CB48CDC9C90700' ### zip_compress(Data: binary | string) -> binary -DEFLATEアルゴリズムで `Data` を圧縮し、zlibヘッダーと末尾のチェックサムを含む圧縮結果を返します。例： +DEFLATEアルゴリズムで `Data` を圧縮し、zlibヘッダーと末尾のチェックサムを含む結果を返します。例： ```bash bin2hexstr(zip_compress('hello')) = '789CCB48CDC9C90700062C0215' @@ -1166,7 +1168,7 @@ zip_uncompress(hexstr2bin('789CCB48CDC9C90700062C0215')) = 'hello' ### bitand(Num1: integer, Num2: integer) -> integer -`Num1` と `Num2` のビットAND演算結果を返します。入力・出力は符号付き整数です。例： +`Num1` と `Num2` のビット単位ANDを返します。入力・出力は符号付き整数です。例： ```bash bitand(10, 8) = 8 @@ -1175,7 +1177,7 @@ bitand(-10, -8) = -16 ### bitnot(Num: integer) -> integer -`Num` のビット否定演算結果を返します。入力・出力は符号付き整数です。例： +`Num` のビット単位否定を返します。入力・出力は符号付き整数です。例： ```bash bitnot(10) = -11 @@ -1204,7 +1206,7 @@ bitsr(-8, 6) = -1 ### bitor(Num1: integer, Num2: integer) -> integer -`Num1` と `Num2` のビットOR演算結果を返します。例： +`Num1` と `Num2` のビット単位ORを返します。例： ```bash bitor(10, 8) = 10 @@ -1213,7 +1215,7 @@ bitor(-10, -8) = -2 ### bitxor(Num1: integer, Num2: integer) -> integer -`Num1` と `Num2` のビットXOR演算結果を返します。例： +`Num1` と `Num2` のビット単位XORを返します。例： ```bash bitxor(10, 8) = 2 @@ -1222,16 +1224,17 @@ bitxor(-10, -8) = 14 ## ビット列操作関数 -ルールエンジンはビット列操作関数を提供します。例えば `subbits` はビット列から指定長のビットを抽出し、指定データ型に変換します。 +ルールエンジンはビット列の操作関数を提供します。例えば `subbits` はビット列から指定長のビットを抽出し、指定データ型に変換します。 :::tip -`binary` 型はバイト列を表し、各バイトは8ビットで構成されるため、ビット数は8の倍数でなければなりません。 -`bitstring` 型は任意長のビット列を表し、8の倍数でなくてもよいです。 +`binary` 型はバイト列を表し、1バイトは8ビットで、バイト数は8の倍数でなければなりません。`bitstring` 型は任意長のビット列を表します。 -つまり、すべての `binary` は `bitstring` ですが、逆は成り立ちません。 +つまり、すべての `binary` は `bitstring` ですが、逆は必ずしも真ではありません。 -`bitstring` の長さが8の倍数でない場合、JSONなど外部フォーマットに直接シリアライズできません。通常は整数など適切な型に変換する前の中間値として利用されます。 +`bitstring` の長さが8の倍数でない場合、JSONなど外部形式に直接シリアライズできません。 + +通常は整数などに変換する前の中間値として使われます。 ::: @@ -1255,7 +1258,7 @@ byteszie('你好') = 6 ### subbits(Bin: binary, BitNum: integer) -> integer -バイト列 `Bin` の先頭から長さ `BitNum` のビットを抽出し、ビッグエンディアンの符号なし整数に変換します。これは `subbits(Bytes, 1, BitNum, 'integer', 'unsigned', 'big')` と同等です。 +バイト列 `Bin` の先頭から `BitNum` ビットを抽出し、ビッグエンディアンの符号なし整数に変換します。`subbits(Bytes, 1, BitNum, 'integer', 'unsigned', 'big')` と同等です。 例： @@ -1272,7 +1275,7 @@ subbits(base64_decode('n05Y'), 8) = 159 ### subbits(Bin: binary, Start: integer, BitNum: integer) -> integer -バイト列 `Bin` の位置 `Start`（1始まり）から長さ `BitNum` のビットを抽出し、ビッグエンディアンの符号なし整数に変換します。これは `subbits(Bytes, Start, BitNum, 'integer', 'unsigned', 'big')` と同等です。 +バイト列 `Bin` の位置 `Start`（1始まり）から `BitNum` ビットを抽出し、ビッグエンディアンの符号なし整数に変換します。`subbits(Bytes, Start, BitNum, 'integer', 'unsigned', 'big')` と同等です。 例： @@ -1289,20 +1292,11 @@ subbits(base64_decode('n05Y'), 9, 4) = 4 ### subbits(Bin: binary, Start: integer, BitNum: integer, OutputType: string, Signedness: string, Endianness: string) -> bitstring | integer | float -バイト列 `Bin` の位置 `Start`（1始まり）から長さ `BitNum` のビットを抽出し、指定したバイト順 `Endianness` と符号属性 `Signedness` に従い、指定型 `OutputType` に変換します。 - -- `OutputType` の可能な値： - - bits（bitstringの略） - - integer - - float - -- `Signedness` の可能な値： - - signed - - unsigned +バイト列 `Bin` の位置 `Start`（1始まり）から `BitNum` ビットを抽出し、指定のバイト順 `Endianness` と符号属性 `Signedness` に従い、指定型 `OutputType` に変換します。 -- `Endianness` の可能な値： - - big - - little +- `OutputType` の値：`bits`（bitstringの略）、`integer`、`float` +- `Signedness` の値：`signed`、`unsigned` +- `Endianness` の値：`big`、`little` `OutputType` が `float` の場合、`Signedness` は無効です。`OutputType` が `bits` の場合、`Signedness` と `Endianness` は無効です。 @@ -1324,7 +1318,7 @@ subbits(hexstr2bin('9F4E58'), 1, 16, 'float', 'signed', 'big') = -0.007133483886 ### base64_decode(Data: string) -> bytes | string -`Data` をBase64形式からデコードします。例： +`Data` をbase64形式からデコードします。例： ```bash base64_decode('aGVsbG8=') = 'hello' @@ -1333,7 +1327,7 @@ bin2hexstr(base64_decode('y0jN')) = 'CB48CD' ### base64_encode(Data: binary | string) -> string -`Data` をBase64形式にエンコードします。例： +`Data` をbase64形式にエンコードします。例： ```bash base64_encode('hello') = 'aGVsbG8=' @@ -1358,7 +1352,7 @@ json_encode([1,2,3]) = '[1,2,3]' ### bin2hexstr(Data: binary) -> string -バイナリデータを対応する16進文字列に変換します。例： +バイナリデータを対応する16進数文字列に変換します。例： ```bash bin2hexstr(zip('hello')) = 'CB48CDC9C90700' @@ -1366,7 +1360,7 @@ bin2hexstr(zip('hello')) = 'CB48CDC9C90700' ### hexstr2bin(Data: string) -> binary -16進文字列を対応するバイナリデータに変換します。例： +16進数文字列を対応するバイナリデータに変換します。例： ```bash unzip(hexstr2bin('CB48CDC9C90700')) = 'hello' @@ -1374,11 +1368,11 @@ unzip(hexstr2bin('CB48CDC9C90700')) = 'hello' ### sqlserver_bin2hexstr(Data: binary | string) -> string -任意のバイナリデータをMicrosoft SQL Serverのバイナリ型に変換します。`0x` プレフィックス付きのHEXエンコード文字列になります。 +任意のバイナリデータをMicrosoft SQL Serverのバイナリ型（`0x` プレフィックス付きHEXエンコード文字列）に変換します。 ::: tip -この関数はMicrosoft SQL Serverの `CONVERT` 関数と組み合わせて、UTF-8非対応のSQL ServerバージョンにUTF-16リトルエンディアンエンコードのUnicode文字列を書き込む際に利用できます。 +この関数はMicrosoft SQL Serverの `CONVERT` 関数と組み合わせて、UTF-8非対応のSQL ServerバージョンにUTF-16リトルエンディアンエンコードされたUnicode文字列を書き込む際に利用できます。 ::: @@ -1390,7 +1384,7 @@ sqlserver_bin2hexstr(str_utf16_le('你好')) = '0x604F7D59' ### スキーマレジストリ関数 -EMQXは `schema_encode` と `schema_decode` 関数を使い、指定したスキーマに基づいて [Protobuf (Protocol Buffers)](https://developers.google.com/protocol-buffers) や [Avro](https://avro.apache.org/) のデータをデコード・エンコードできます。詳細は [Schema Registry](./schema-registry.md) を参照してください。 +EMQXは `schema_encode` と `schema_decode` 関数を使い、指定したスキーマに従って [Protobuf (Protocol Buffers)](https://developers.google.com/protocol-buffers) や [Avro](https://avro.apache.org/) データのエンコード・デコードをサポートしています。詳細は[スキーマレジストリ](./schema-registry.md)を参照してください。 ### schema_encode(SchemaID: string, Data: map) -> binary @@ -1406,28 +1400,28 @@ EMQXは `schema_encode` と `schema_decode` 関数を使い、指定したスキ ### schema_decode(SchemaID: string, Bin: binary, MsgType: string) -> map -指定したProtobufスキーマで `Bin` をデコードします。スキーマレジストリでスキーマを作成しIDを取得してください。`MsgType` はProtobufスキーマ内の `Data` に対応するメッセージタイプを指定します。 +指定したProtobufスキーマで `Bin` をデコードします。スキーマレジストリでスキーマを作成しIDを取得してください。`MsgType` はProtobufスキーマ内のデータに対応するメッセージタイプを指定します。 ### **Sparkplug B関数** -EMQXはSparkplug Bメッセージのデコード・エンコード用の特殊関数（`sparkplug_decode` と `sparkplug_encode`）も備えています。詳細は [Sparkplug B](./sparkplug.md) を参照してください。 +EMQXはSparkplug Bメッセージのデコード・エンコード用の特殊関数（`sparkplug_decode` と `sparkplug_encode`）も備えています。詳細は[Sparkplug B](./sparkplug.md)を参照してください。 ## 日時変換関数 ### date_to_unix_ts(Unit: string, FormatString: string, DateTimeString: string) -> integer -日時文字列 `DateTimeString` をフォーマット文字列 `FormatString` に従って解析し、指定した時間単位 `Unit` のUnix時間に変換します。 +日時文字列 `DateTimeString` をフォーマット文字列 `FormatString` に従って解析し、指定単位 `Unit` のUnix時間に変換します。 利用可能な `Unit` は `second`, `millisecond`, `microsecond`, `nanosecond` です。 `FormatString` で使えるプレースホルダーは以下の通りです： | プレースホルダー | 意味 | 値の範囲 | -| ------ | ---------------------------------- | ----- ---------------- | +| ----------- | ------- | ------------| | `%Y` | 4桁の年 | 0000 - 9999 | | `%m` | 2桁の月 | 01 - 12 | | `%d` | 2桁の日 | 01 - 31 | -| `%H` | 24時間表記の2桁の時 | 00 - 24 | +| `%H` | 24時間制の2桁の時 | 00 - 24 | | `%M` | 2桁の分 | 00 - 59 | | `%S` | 2桁の秒 | 00 - 59 | | `%N` | ナノ秒 | 000000000 - 999999999 | @@ -1445,12 +1439,12 @@ date_to_unix_ts('second', '%Y-%m-%d %H:%M:%S%:z', '2024-02-23 15:00:00+08:00') = ### date_to_unix_ts(Unit: string, Offset: string | integer, FormatString: string, DateTimeString: string) -> integer -`DateTimeString` にタイムゾーンオフセットが含まれない場合、`Offset` で手動指定できます。その他の動作は `date_to_unix_ts/3` と同様です。`Offset` は文字列または秒数の整数で指定可能です。 +`DateTimeString` にタイムゾーンオフセットが含まれない場合、`Offset` で手動指定できます。その他は `date_to_unix_ts/3` と同様です。`Offset` は文字列または秒数の整数で指定可能です。 -文字列の場合、以下の形式をサポートします： +文字列の形式は以下の通りです： -- `Z` または `z`：UTCオフセット00:00 -- `±hh[:mm][:ss]` または `±hh[mm][ss]`：UTCからの正負の時間オフセット +- `Z` または `z`：UTCオフセット00:00 +- `±hh[:mm][:ss]` または `±hh[mm][ss]`：UTCからの正負の時間オフセット - `local`：システムのローカルタイムゾーンに対応するオフセット 例： @@ -1463,9 +1457,9 @@ date_to_unix_ts('second', 14400, '%Y-%m-%d %H:%M:%S%:z', '2024-02-23 15:00:00') ### format_date(Unit: string, Offset: string | integer, FormatString: string, Time: Integer) -> string -Unix時間 `Time` を指定フォーマットの日時文字列に変換します。`Unit` はUnix時間の単位、`Offset` は出力日時のタイムゾーンオフセット、`FormatString` は出力フォーマットを表します。 +Unix時間 `Time` を指定フォーマットの日時文字列に変換します。`Unit` はUnix時間の単位、`Offset` は出力日時のタイムゾーンオフセット、`FormatString` は出力日時のフォーマットです。 -`date_to_unix_ts/3, 4` を参照し、`Unit`, `Offset`, `FormatString` の値を指定してください。 +`date_to_unix_ts/3,4` を参照してください。 例： @@ -1479,7 +1473,7 @@ format_date('millisecond', 28800, '%Y-%m-%d %H:%M:%S.%3N%:z', 1708933353472) = ' ### now_rfc3339() -> string -現在のシステム時刻を秒単位のRFC3339形式日時文字列で返します。例： +現在のシステム時刻を秒単位のRFC3339日時文字列で返します。例： ```bash now_rfc3339() = '2024-02-23T10:26:20+08:00' @@ -1487,7 +1481,7 @@ now_rfc3339() = '2024-02-23T10:26:20+08:00' ### now_rfc3339(Unit: string) -> string -`now_rfc3339/0` と同様ですが、`Unit` で時間単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポートします。例： +`now_rfc3339/0` と同様ですが、`Unit` で時刻単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポートします。例： ```bash now_rfc3339('microsecond') = '2024-02-23T10:26:38.009706+08:00' @@ -1503,7 +1497,7 @@ now_timestamp() = 1708913853 ### now_timestamp(Unit: string) -> integer -`now_timestamp/0` と同様ですが、`Unit` で時間単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポートします。例： +`now_timestamp/0` と同様ですが、`Unit` で時刻単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポートします。例： ```bash now_timestamp('microsecond') = 1708913828814315 @@ -1533,8 +1527,8 @@ rfc3339_to_unix_ts('2024-02-23T15:56:30.535904509Z', 'nanosecond') = 17087037905 タイムゾーンオフセット文字列を秒数の整数に変換します。以下の形式をサポートします： -- `Z` または `z`：UTCオフセット00:00 -- `±hh[:mm][:ss]` または `±hh[mm][ss]`：UTCからの正負の時間オフセット +- `Z` または `z`：UTCオフセット00:00 +- `±hh[:mm][:ss]` または `±hh[mm][ss]`：UTCからの正負の時間オフセット - `local`：システムのローカルタイムゾーンに対応するオフセット 例： @@ -1547,7 +1541,7 @@ timezone_to_offset_seconds('local') = 28800 ### unix_ts_to_rfc3339(Time: integer) -> string -秒単位のUnixタイムスタンプをシステムのローカルタイムゾーンでRFC3339準拠の日時文字列に変換します。例： +秒単位のUnixタイムスタンプをシステムのローカルタイムゾーンを用いたRFC3339準拠の日時文字列に変換します。例： ```bash unix_ts_to_rfc3339(1708671600) = '2024-02-23T15:00:00+08:00' @@ -1555,7 +1549,7 @@ unix_ts_to_rfc3339(1708671600) = '2024-02-23T15:00:00+08:00' ### unix_ts_to_rfc3339(Time: integer, Unit: string) -> string -`unix_ts_to_rfc3339/0` と同様ですが、`Unit` で時間単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポートします。例： +`unix_ts_to_rfc3339/0` と同様ですが、`Unit` で時刻単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポートします。例： ```bash unix_ts_to_rfc3339(1708671600766, 'millisecond') = '2024-02-23T15:00:00.766+08:00' @@ -1565,7 +1559,7 @@ unix_ts_to_rfc3339(1708671600766, 'millisecond') = '2024-02-23T15:00:00.766+08:0 ### mongo_date() -> [MongoDB ISODate](https://www.mongodb.com/docs/manual/reference/method/Date/) | string -現在時刻をMongoDBのISODate型または文字列で返します。MongoDB関連のアクションやSQLテストでのみサポートされ、SQLテストでは文字列（例：`ISODate("2024-02-23T15:00:00.123Z")`）を返します。文字列以外の戻り値は他の関数の入力としては現在サポートされていません。 +現在時刻をMongoDBのISODate型または文字列で返します。MongoDB関連アクションとSQLテストでのみサポートされます。SQLテストでは文字列（例：`ISODate("2024-02-23T15:00:00.123Z")`）を返します。文字列以外の戻り値は他関数の入力としては未対応です。 例： @@ -1575,7 +1569,7 @@ mongo_date() = 'ISODate("2024-02-23T15:00:00.123Z")' ### mongo_date(Timestamp: integer) -> [MongoDB ISODate](https://www.mongodb.com/docs/manual/reference/method/Date/) | string -指定したミリ秒単位のUnixタイムスタンプをMongoDBのISODate型または文字列に変換します。その他の動作は `mongo_date/0` と同様です。 +指定したミリ秒単位UnixタイムスタンプをMongoDB ISODate型または文字列に変換します。その他は `mongo_date/0` と同様です。 例： @@ -1585,13 +1579,13 @@ mongo_date(now_timestamp('millisecond')) = 'ISODate(2024-02-23T15:48:57.871Z)' ### mongo_date(Timestamp: integer, Unit: string) -> [MongoDB ISODate](https://www.mongodb.com/docs/manual/reference/method/Date/) | string -指定したUnixタイムスタンプをMongoDBのISODate型または文字列に変換します。`Unit` で入力タイムスタンプの単位を指定できます。その他の動作は `mongo_date/0` と同様です。 +指定したUnixタイムスタンプをMongoDB ISODate型または文字列に変換します。`Unit` で入力タイムスタンプの単位を指定できます。その他は `mongo_date/0` と同様です。 -利用可能な `Unit` は： +利用可能な `Unit`： -- `second` -- `millisecond` -- `microsecond` +- `second` +- `millisecond` +- `microsecond` - `nanosecond` 例： @@ -1624,20 +1618,24 @@ uuid_v4_no_hyphen() = 'd7a39aa4195a42068b962eb9a665503e' 環境変数 `Name` の値を返します。以下の制約があります： -- OS環境変数を読み取る際、`EMQXVAR_` プレフィックスが付加されます。例えば、`getenv('FOO_BAR')` は `EMQXVAR_FOO_BAR` を読み取ります。 +- OS環境変数を読む際に `EMQXVAR_` プレフィックスが付加されます。例えば、`getenv('FOO_BAR')` は `EMQXVAR_FOO_BAR` を読みます。 - OS環境変数から読み込んだ値は不変です。 ## 条件関数 ### coalesce(Value1: any, Value2: any) -> any -`Value1` がnullの場合に `Value2` を返します。データフィールドがnullかどうかをチェックし、デフォルト値に置き換えたい場合に便利です。 +`Value1` がnullの場合に `Value2` を返します。 + +データフィールドがnullかどうかを判定し、デフォルト値に置き換えたい場合に便利です。 + +例えば、`coalesce(payload.value, 0)` は `payload.value` がnullでなければその値を、nullであれば0を返します。 -例えば、`coalesce(payload.value, 0)` は `payload.value` がnullでなければその値を返し、nullなら0を返します。SQL式の `CASE WHEN is_null(payload.value) THEN 0 ELSE payload.value END` と同等ですが簡潔です。 +SQL式の `CASE WHEN is_null(payload.value) THEN 0 ELSE payload.value END` と同等ですが簡潔です。 ::: tip 注意 -EMQXルールSQLでは、null値の文字列表現はデフォルトで `'undefined'` です。 +EMQXルールSQLではnull値の文字列表現はデフォルトで `'undefined'` です。 ::: @@ -1647,6 +1645,6 @@ EMQXルールSQLでは、null値の文字列表現はデフォルトで `'undefi ::: tip 注意 -EMQXルールSQLでは、null値の文字列表現はデフォルトで `'undefined'` です。 +EMQXルールSQLではnull値の文字列表現はデフォルトで `'undefined'` です。 ::: diff --git a/ja_JP/data-integration/snowflake.md b/ja_JP/data-integration/snowflake.md index 1d7858735..f2b2b3cf8 100644 --- a/ja_JP/data-integration/snowflake.md +++ b/ja_JP/data-integration/snowflake.md @@ -1,93 +1,146 @@ -# Snowflake への MQTT データ取り込み +# SnowflakeへのMQTTデータ取り込み -[Snowflake](https://www.snowflake.com/en/) は、クラウドベースのデータプラットフォームであり、高いスケーラビリティと柔軟性を備えたデータウェアハウジング、分析、および安全なデータ共有のソリューションを提供します。構造化データおよび半構造化データの処理に優れ、大量のデータを高速なクエリ性能で保存し、さまざまなツールやサービスとシームレスに統合できるよう設計されています。 +[Snowflake](https://www.snowflake.com/en/)は、クラウドベースのデータプラットフォームであり、データウェアハウジング、分析、および安全なデータ共有に対して高いスケーラビリティと柔軟性を提供します。構造化データおよび半構造化データの処理に優れており、大量のデータを高速なクエリ性能で保存し、さまざまなツールやサービスとのシームレスな統合を実現するよう設計されています。 -本ページでは、EMQX と Snowflake 間のデータ統合について詳しく紹介し、ルールおよび Sink の作成方法について実践的なガイドを提供します。 +本ページでは、EMQXとSnowflake間のデータ統合について詳細に紹介し、ルールおよびSinkの作成に関する実践的なガイドを提供します。 ## 動作概要 -EMQX における Snowflake データ統合はすぐに使える機能であり、複雑なビジネス開発にも簡単に設定可能です。典型的な IoT アプリケーションでは、EMQX がデバイス接続とメッセージ送受信を担う IoT プラットフォームとして機能し、Snowflake はメッセージデータの取り込み、保存、分析を担当するデータストレージおよび処理プラットフォームとして利用されます。 +EMQXにおけるSnowflakeデータ統合はすぐに使える機能であり、複雑なビジネス開発にも簡単に設定可能です。典型的なIoTアプリケーションでは、EMQXがデバイス接続とメッセージ送信を担うIoTプラットフォームとして機能し、Snowflakeはメッセージデータの取り込み、保存、分析を行うデータストレージおよび処理プラットフォームとして利用されます。 ![snowflake-architecture](./assets/snowflake-architecture.png) -EMQX はルールエンジンと Sink を利用してデバイスイベントやデータを Snowflake に転送します。エンドユーザーやアプリケーションは Snowflake のテーブル内のデータにアクセスできます。具体的なワークフローは以下の通りです： +EMQXはルールエンジンとSinkを利用してデバイスイベントやデータをSnowflakeに転送します。エンドユーザーやアプリケーションはSnowflakeのテーブルに格納されたデータにアクセス可能です。具体的なワークフローは以下の通りです。 -1. **デバイスの EMQX への接続**：IoT デバイスは MQTT プロトコルで正常に接続するとオンラインイベントをトリガーします。イベントにはデバイスID、送信元IPアドレスなどの情報が含まれます。 -2. **デバイスメッセージのパブリッシュと受信**：デバイスは特定のトピックを通じてテレメトリや状態データをパブリッシュします。EMQX はメッセージを受信し、ルールエンジン内で比較処理を行います。 -3. **ルールエンジンによるメッセージ処理**：組み込みのルールエンジンはトピックマッチングに基づき特定のソースからのメッセージやイベントを処理します。対応するルールをマッチングし、データ形式変換、特定情報のフィルタリング、コンテキスト情報の付加などの処理を行います。 -4. **Snowflake への書き込み**：ルールはメッセージを Snowflake Stage に書き込み、そこから Snowflake テーブルにロードするアクションをトリガーします。 +1. **デバイスのEMQXへの接続**：IoTデバイスはMQTTプロトコルで正常に接続されるとオンラインイベントをトリガーします。このイベントにはデバイスID、送信元IPアドレス、その他のプロパティ情報が含まれます。 +2. **デバイスのメッセージパブリッシュと受信**：デバイスは特定のトピックを通じてテレメトリおよびステータスデータをパブリッシュします。EMQXはメッセージを受信し、ルールエンジン内で比較処理を行います。 +3. **ルールエンジンによるメッセージ処理**：組み込みのルールエンジンはトピックマッチングに基づき特定のソースからのメッセージやイベントを処理します。対応するルールにマッチしたメッセージやイベントに対して、データ形式変換、特定情報のフィルタリング、コンテキスト情報の付加などの処理を行います。 +4. **Snowflakeへの書き込み**：ルールはSnowflake Stageへのメッセージ書き込みアクションをトリガーし、Snowflakeテーブルにロードします。 -イベントやメッセージデータが Snowflake に書き込まれた後は、以下のようなビジネスや技術的な目的で利用可能です： +イベントおよびメッセージデータがSnowflakeに書き込まれた後、以下のようなビジネスおよび技術的用途で活用可能です。 -- **データアーカイブ**：IoT データを Snowflake に安全に長期保存し、コンプライアンスや過去データの利用を保証します。 -- **データ分析**：Snowflake のデータウェアハウジングおよび分析機能を活用し、リアルタイムまたはバッチ分析を行い、予知保全、運用インサイト、デバイス性能評価を可能にします。 +- **データアーカイブ**：IoTデータをSnowflakeに安全に長期保存し、コンプライアンスや履歴データの利用を保証します。 +- **データ分析**：Snowflakeのデータウェアハウジングおよび分析機能を活用し、リアルタイムまたはバッチ分析を行い、予知保全、運用インサイト、デバイス性能評価を実現します。 -## 特長と利点 +## 特長とメリット -EMQX の Snowflake データ統合を利用することで、以下の特長と利点が得られます： +EMQXにおけるSnowflakeデータ統合を利用することで、以下の特長とメリットが得られます。 -- **メッセージ変換**：メッセージは EMQX のルール内で高度な処理や変換を経てから Snowflake に書き込まれるため、後続の保存や利用が容易になります。 -- **柔軟なデータ操作**：Snowflake Sink は、書き込むフィールドを選択可能であり、ビジネスニーズに応じた効率的かつ動的なストレージ構成が可能です。 -- **統合されたビジネスプロセス**：Snowflake Sink によりデバイスデータを Snowflake の豊富なエコシステムアプリケーションと組み合わせ、データ分析やアーカイブなど多様なビジネスシナリオを実現します。 -- **低コストの長期保存**：Snowflake のスケーラブルなストレージ基盤は、従来のデータベースに比べて低コストで長期データ保持に最適なソリューションです。大量の IoT データ保存に適しています。 +- **メッセージ変換**：メッセージはSnowflakeへの書き込み前にEMQXルール内で高度な処理・変換が可能であり、その後の保存や利用を容易にします。 +- **柔軟なデータ操作**：Snowflake Sinkは書き込むフィールドを選択可能で、ビジネスニーズに応じた効率的かつ動的なストレージ構成を実現します。 +- **統合されたビジネスプロセス**：Snowflake SinkによりデバイスデータをSnowflakeの豊富なエコシステムアプリケーションと組み合わせ、データ分析やアーカイブなど多様なビジネスシナリオを実現します。 +- **低コストの長期保存**：Snowflakeのスケーラブルなストレージ基盤は従来のデータベースに比べ低コストで長期データ保持に最適であり、大量のIoTデータ保存に適しています。 -これらの特長により、効率的で信頼性が高くスケーラブルな IoT アプリケーションを構築し、ビジネスの意思決定や最適化に役立てることができます。 +これらの特長により、効率的で信頼性が高くスケーラブルなIoTアプリケーション構築と、ビジネス意思決定や最適化に貢献します。 ## はじめる前に -このセクションでは、EMQX で Snowflake Sink を作成する前に必要な準備について説明します。 +本節では、EMQXでSnowflake Sinkを作成する前の準備について説明します。 ### 前提条件 -- [ルール](./rules.md) の理解 -- [データ統合](./data-bridges.md) の理解 +- [ルール](./rules.md)の理解 +- [データ統合](./data-bridges.md)の理解 -### Snowflake ODBC ドライバーの初期化 +### Snowflake ODBCドライバーの初期化 -EMQX が Snowflake と通信し効率的にデータ転送を行うために、Snowflake Open Database Connectivity (ODBC) ドライバーのインストールと設定が必要です。これは通信の橋渡し役となり、データの適切なフォーマット、認証、転送を保証します。 +EMQXがSnowflakeと通信し効率的にデータ転送を行うためには、SnowflakeのOpen Database Connectivity（ODBC）ドライバーをインストールおよび設定する必要があります。これは通信の橋渡し役を担い、データの正しいフォーマット化、認証、転送を保証します。 -詳細は公式の [ODBC Driver](https://docs.snowflake.com/en/developer-guide/odbc/odbc) ページおよび [ライセンス契約](https://sfc-repo.snowflakecomputing.com/odbc/Snowflake_ODBC_Driver_License_Agreement.pdf) を参照してください。 +詳細は公式の[ODBC Driver](https://docs.snowflake.com/en/developer-guide/odbc/odbc)ページおよび[ライセンス契約](https://sfc-repo.snowflakecomputing.com/odbc/Snowflake_ODBC_Driver_License_Agreement.pdf)を参照してください。 #### Linux -以下のスクリプトを実行して Snowflake ODBC ドライバーをインストールし、`odbc.ini` ファイルを設定します： +EMQXはDebian系システム（Ubuntuなど）向けにSnowflake ODBCドライバーの迅速な導入と必要なシステム設定を行う[インストールスクリプト](https://github.com/emqx/emqx/blob/master/scripts/install-snowflake-driver.sh)を提供しています。 +::: tip 注意 + +このスクリプトはテスト目的のものであり、本番環境でのODBCドライバー設定方法の推奨ではありません。公式の[Linux向けインストール手順](https://docs.snowflake.com/en/developer-guide/odbc/odbc-linux)を参照してください。 + +::: + +**インストールスクリプトの実行** + +`scripts/install-snowflake-driver.sh`スクリプトをローカルにコピーし、`chmod a+x`で実行権限を付与後、`sudo`で実行します。 + +```bash +chmod a+x scripts/install-snowflake-driver.sh +sudo ./scripts/install-snowflake-driver.sh ``` -scripts/install-snowflake-driver.sh + +スクリプトはSnowflake ODBCの`.deb`インストールパッケージ（例：`snowflake-odbc-3.4.1.x86_64.deb`）をカレントディレクトリに自動ダウンロードし、ドライバーをインストール、以下のシステム設定ファイルを更新します。 + +- `/etc/odbc.ini`：Snowflakeデータソース設定を追加 +- `/etc/odbcinst.ini`：Snowflakeドライバーのパスを登録 + +**設定例** + +以下のコマンドで`/etc/odbc.ini`の設定を確認できます。 + ``` +emqx@emqx-0:~$ cat /etc/odbc.ini -::: tip 注意 +[snowflake] +Description=SnowflakeDB +Driver=SnowflakeDSIIDriver +Locale=en-US +PORT=443 +SSL=on -このスクリプトはテスト用であり、本番環境での ODBC ドライバー設定方法の推奨ではありません。公式の [Linux 向けインストール手順](https://docs.snowflake.com/en/developer-guide/odbc/odbc-linux) を参照してください。 +[ODBC Data Sources] +snowflake = SnowflakeDSIIDriver +``` -::: +以下のコマンドで`/etc/odbcinst.ini`の設定を確認できます。 + +``` +emqx@emqx-0:~$ cat /etc/odbcinst.ini + +[ODBC Driver 18 for SQL Server] +Description=Microsoft ODBC Driver 18 for SQL Server +Driver=/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.5.so.1.1 +UsageCount=1 + +[ODBC Driver 17 for SQL Server] +Description=Microsoft ODBC Driver 17 for SQL Server +Driver=/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.10.so.6.1 +UsageCount=1 + +[SnowflakeDSIIDriver] +APILevel=1 +ConnectFunctions=YYY +Description=Snowflake DSII +Driver=/usr/lib/snowflake/odbc/lib/libSnowflake.so +DriverODBCVer=03.52 +SQLLevel=1 +UsageCount=1 +``` #### macOS -macOS で Snowflake ODBC ドライバーをインストールおよび設定する手順は以下の通りです： +macOSでSnowflake ODBCドライバーをインストールおよび設定する手順は以下の通りです。 -1. unixODBC をインストール（例）： +1. unixODBCをインストール（例）： ``` brew install unixodbc ``` -2. [iODBC をダウンロードしてインストール](https://github.com/openlink/iODBC/releases/download/v3.52.16/iODBC-SDK-3.52.16-macOS11.dmg)。 +2. [iODBCのダウンロードとインストール](https://github.com/openlink/iODBC/releases/download/v3.52.16/iODBC-SDK-3.52.16-macOS11.dmg)。 -3. [Snowflake ODBC ドライバーをダウンロードしてインストール](https://sfc-repo.snowflakecomputing.com/odbc/macuniversal/3.3.2/snowflake_odbc_mac_64universal-3.3.2.dmg)。 +3. [Snowflake ODBCドライバーのダウンロードとインストール](https://sfc-repo.snowflakecomputing.com/odbc/macuniversal/3.3.2/snowflake_odbc_mac_64universal-3.3.2.dmg)。 -4. 詳細なインストールおよび設定手順は [macOS 向け ODBC ドライバーのインストールと設定](https://docs.snowflake.com/en/developer-guide/odbc/odbc-mac) を参照してください。 +4. 詳細なインストールおよび設定手順は[macOS向けODBCドライバーのインストールと設定](https://docs.snowflake.com/en/developer-guide/odbc/odbc-mac)を参照。 -5. インストール後、以下の設定ファイルを更新します： +5. インストール後、以下の設定ファイルを更新： - - Snowflake ODBC ドライバーの権限と設定を更新： + - Snowflake ODBCドライバーの権限と設定を更新： ```bash chown $(id -u):$(id -g) /opt/snowflake/snowflakeodbc/lib/universal/simba.snowflake.ini echo 'ODBCInstLib=libiodbcinst.dylib' >> /opt/snowflake/snowflakeodbc/lib/universal/simba.snowflake.ini ``` - - `~/.odbc.ini` ファイルを作成または更新して ODBC 接続を設定： + - ODBC接続設定のため、`~/.odbc.ini`ファイルを作成または更新： ``` cat << EOF > ~/.odbc.ini @@ -108,36 +161,36 @@ macOS で Snowflake ODBC ドライバーをインストールおよび設定す ### ユーザーアカウントとデータベースの作成 -Snowflake ODBC ドライバーをインストールしたら、データ取り込み用のユーザーアカウント、データベース、および関連リソースを設定します。これらの認証情報は後で EMQX のコネクターおよび Sink 設定時に使用します。 +Snowflake ODBCドライバーのインストール後、データ取り込み用のユーザーアカウント、データベース、関連リソースを設定する必要があります。これらの認証情報は後でEMQXのコネクターおよびSink設定時に使用します。 -| フィールド名 | 値 | -| -------------------------- | ------------------------------------------------ | -| Data Source Name (DSN) | `snowflake` | -| ユーザー名 | `snowpipeuser` | -| パスワード | `Snowpipeuser99` | -| データベース名 | `testdatabase` | -| スキーマ | `public` | -| ステージ | `emqx` | -| パイプ | `emqx` | -| パイプユーザー | `snowpipeuser` | -| プライベートキー | `file://` | +| 項目 | 値 | +| ----------------------- | ------------------------------------------------ | +| データソース名 (DSN) | `snowflake` | +| ユーザー名 | `snowpipeuser` | +| パスワード | `Snowpipeuser99` | +| データベース名 | `testdatabase` | +| スキーマ | `public` | +| ステージ | `emqx` | +| パイプ | `emqx` | +| パイプユーザー | `snowpipeuser` | +| プライベートキー | `file://` | -#### RSA キーペアの生成 +#### RSA鍵ペアの生成 -Snowflake への安全な接続のため、以下のコマンドで認証用の RSA キーペアを生成します： +Snowflakeへの安全な接続のため、以下のコマンドでRSA鍵ペアを生成します。 ```bash openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out snowflake_rsa_key.private.pem -nocrypt openssl rsa -in snowflake_rsa_key.private.pem -pubout -out snowflake_rsa_key.public.pem ``` -詳細は [キーペア認証とキーペアローテーション](https://docs.snowflake.com/en/user-guide/key-pair-auth) を参照してください。 +詳細は[鍵ペア認証と鍵ペアローテーション](https://docs.snowflake.com/en/user-guide/key-pair-auth)を参照してください。 -#### SQL を使った Snowflake リソースのセットアップ +#### SQLによるSnowflakeリソースの設定 -ODBC ドライバーのセットアップと RSA キーペア生成後、Snowflake のリソースを設定します。SQL コマンドを使ってデータベース、テーブル、ステージ、パイプを作成します。 +ODBCドライバーの設定とRSA鍵ペアの生成が完了したら、SQLコマンドでSnowflakeのリソース（データベース、テーブル、ステージ、パイプ）を作成します。 -1. Snowflake コンソールの SQL ワークシートを開き、以下の SQL を実行してデータベース、テーブル、ステージ、パイプを作成します： +1. SnowflakeコンソールでSQLワークシートを開き、以下のSQLを実行してデータベース、テーブル、ステージ、パイプを作成します。 ```sql USE ROLE accountadmin; @@ -161,7 +214,7 @@ ODBC ドライバーのセットアップと RSA キーペア生成後、Snowfla MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE; ``` -2. 新しいユーザーを作成し、そのユーザーに RSA 公開鍵を設定します： +2. 新規ユーザーを作成し、そのユーザーにRSA公開鍵を設定します。 ```sql CREATE USER IF NOT EXISTS snowpipeuser @@ -178,11 +231,11 @@ ODBC ドライバーのセットアップと RSA キーペア生成後、Snowfla ::: tip - PEM ファイルの `-----BEGIN PUBLIC KEY-----` および `-----END PUBLIC KEY-----` 行は削除し、残りの内容を改行を保持したまま含めてください。 + PEMファイルの`-----BEGIN PUBLIC KEY-----`および`-----END PUBLIC KEY-----`の行は削除し、残りの内容は改行を保持して含めてください。 ::: -3. ユーザーが Snowflake リソースを管理できるように必要なロールを作成し割り当てます： +3. Snowflakeリソース管理用のロールを作成し、ユーザーに割り当てます。 ```sql CREATE OR REPLACE ROLE snowpipe; @@ -198,34 +251,62 @@ ODBC ドライバーのセットアップと RSA キーペア生成後、Snowfla ## コネクターの作成 -Snowflake Sink を追加する前に、EMQX で Snowflake への接続を確立するためのコネクターを作成します。 +Snowflake Sinkを追加する前に、EMQXでSnowflakeとの接続を確立するためのコネクターを作成する必要があります。 1. ダッシュボードの **Integration** -> **Connector** ページに移動します。 + 2. 右上の **Create** ボタンをクリックします。 + 3. コネクタータイプとして **Snowflake** を選択し、次へ進みます。 -4. コネクター名を入力します。英数字の組み合わせで、ここでは `my-snowflake` と入力します。 + +4. コネクター名を英数字の組み合わせで入力します。ここでは `my-snowflake` と入力します。 + 5. 接続情報を入力します。 - - **Account**：Snowflake の組織IDとアカウント名をハイフン（`-`）で区切って入力します。これは Snowflake プラットフォームの URL の一部で、Snowflake コンソールで確認可能です。 - - **Server Host**：Snowflake のエンドポイント URL で、通常 `-.snowflakecomputing.com` の形式です。`-` はご自身の Snowflake インスタンス固有のサブドメインに置き換えてください。 - - **Data Source Name(DSN)**：ODBC ドライバー設定時に `.odbc.ini` ファイルで設定した `snowflake` を入力します。 - - **Username**：前述の設定で作成した `snowpipeuser` を入力します。 - - **Password**：前述の設定で定義した `Snowpipeuser99` を入力します。 -6. 暗号化接続を確立したい場合は、**Enable TLS** のトグルスイッチをオンにします。TLS 接続の詳細は [TLS for External Resource Access](../network/overview.md/#tls-for-external-resource-access) を参照してください。 -7. 詳細設定（任意）：[Advanced Settings](#advanced-settings) を参照してください。 -8. **Create** をクリックする前に、**Test Connectivity** ボタンでコネクターが Snowflake に接続できるかテストできます。 -9. 最後に、ページ下部の **Create** ボタンをクリックしてコネクター作成を完了します。 + - **Server Host**：SnowflakeのエンドポイントURLで、通常は `-.snowflakecomputing.com` の形式です。`-` はSnowflakeインスタンス固有のサブドメインに置き換えてください。 + + - **Data Source Name(DSN)**：ODBCドライバー設定時に`.odbc.ini`ファイルで設定した`snowflake`を入力します。 + + - **Account**：Snowflakeの組織IDとアカウント名をハイフン（`-`）で区切って入力します。これはSnowflakeプラットフォームへのアクセスURLの一部で、Snowflakeコンソールで確認可能です。 + + - **Username**：前述の設定で作成した`snowpipeuser`を入力します。 + + - **Password**：ODBC経由でのユーザー名/パスワード認証に使用するパスワードです。任意入力項目です。 + + - ここにパスワード（例：`Snowpipeuser99`）を入力するか、 + - `/etc/odbc.ini`で設定するか、 + - キーペア認証を使用する場合は空欄のままにします。 + + ::: tip + + 認証にはパスワードかプライベートキーのいずれか一方を使用してください。両方同時には設定しないでください。ここでどちらも設定しない場合は、適切な認証情報が`/etc/odbc.ini`に設定されていることを確認してください。 + + ::: + + - **Proxy**：HTTPプロキシサーバー経由でSnowflakeに接続する場合の設定です。HTTPSプロキシはサポートされていません。デフォルトではプロキシは使用しません。プロキシを有効にするには`Enable Proxy`を選択し、以下を入力します。 + - **Proxy Host**：プロキシサーバーのホスト名またはIPアドレス + - **Proxy Port**：プロキシサーバーのポート番号 + - **Private Key Path**：ODBC経由でSnowflake認証に使用するRSA秘密鍵の絶対ファイルパスです。クラスターの全ノードで同一パスである必要があります。パスは`file://`で始まる必要があります（例：`file:///etc/emqx/certs/snowflake_rsa_key.private.pem`）。 + - **Private Key Password**：秘密鍵ファイルが暗号化されている場合の復号パスワードです。OpenSSLの`-nocrypt`オプションで生成した暗号化なしの鍵の場合は空欄にします。 + +6. 暗号化接続を確立したい場合は、**Enable TLS**のトグルスイッチをオンにします。TLS接続の詳細は[外部リソースアクセスのTLS](../network/overview.md/#tls-for-external-resource-access)を参照してください。 + +7. 詳細設定（任意）：[詳細設定](#advanced-settings)を参照してください。 + +8. **Create**をクリックする前に、**Test Connectivity**をクリックしてコネクターがSnowflakeに接続できるかテストできます。 + +9. 下部の **Create** ボタンをクリックしてコネクター作成を完了します。 -これでコネクターの作成が完了し、次にルールと Sink を作成してデータの書き込み方法を指定できます。 +これでコネクター作成が完了し、次にルールとSinkを作成してデータのSnowflakeへの書き込み方法を指定できます。 -## Snowflake Sink を使ったルールの作成 +## Snowflake Sinkを用いたルールの作成 -このセクションでは、EMQX でソース MQTT トピック `t/#` からのメッセージを処理し、処理結果を設定済みの Snowflake Sink を通じて Snowflake に書き込むルールの作成方法を示します。 +本節では、EMQXでソースMQTTトピック`t/#`からのメッセージを処理し、処理結果を設定済みのSnowflake Sinkを通じてSnowflakeに書き込むルールの作成方法を示します。 1. ダッシュボードの **Integration** -> **Rules** ページに移動します。 2. 右上の **Create** ボタンをクリックします。 -3. ルールID に `my_rule` と入力し、SQL エディターに以下のルール SQL を入力します： +3. ルールIDに `my_rule` を入力し、SQLエディターに以下のルールSQLを入力します。 ```sql SELECT @@ -239,97 +320,96 @@ Snowflake Sink を追加する前に、EMQX で Snowflake への接続を確立 ::: tip - SQL に不慣れな場合は、**SQL Examples** をクリックし、**Enable Debug** を有効にしてルール SQL の結果を学習・テストできます。 + SQLに不慣れな場合は、**SQL Examples**や**Enable Debug**をクリックしてルールSQLの学習やテストが可能です。 ::: - ::: tip - - Snowflake 連携では、選択するフィールドが Snowflake 側で定義したテーブルのカラム数および名前と完全に一致していることが重要です。余分なフィールドを追加したり、`*` で全選択することは避けてください。 - + + Snowflake連携では、選択するフィールドがSnowflakeで定義したテーブルの列数および名前と完全に一致することが重要です。余分なフィールドの追加や`*`による全選択は避けてください。 + ::: -4. アクションを追加し、**Action Type** ドロップダウンリストから `Snowflake` を選択します。アクションのドロップダウンはデフォルトの `create action` のままにするか、既存の Snowflake アクションを選択します。ここでは新しい Sink を作成してルールに追加します。 +4. アクションを追加し、**Action Type**のドロップダウンから`Snowflake`を選択します。アクションドロップダウンはデフォルトの`create action`のままにするか、既存のSnowflakeアクションを選択します。ここでは新規Sinkを作成してルールに追加します。 -5. Sink の名前（例：`snowflake_sink`）と簡単な説明を入力します。 +5. Sinkの名前（例：`snowflake_sink`）と簡単な説明を入力します。 -6. 先に作成した `my-snowflake` コネクターをコネクタードロップダウンから選択します。ドロップダウン横の作成ボタンをクリックしてポップアップで新規コネクターを素早く作成することも可能です。必要な設定パラメータは [Create a Connector](#create-a-connector) を参照してください。 +6. コネクターのドロップダウンから先ほど作成した`my-snowflake`を選択します。ドロップダウン横の作成ボタンを押すとポップアップで新規コネクター作成も可能です。必要な設定パラメータは[コネクターの作成](#コネクターの作成)を参照してください。 -7. 以下の設定を行います： +7. 以下の設定を行います。 - - **Database Name**：`testdatabase` を入力。EMQX データ保存用に作成した Snowflake データベースです。 - - **Schema**：`public` を入力。`testdatabase` 内のデータテーブルがあるスキーマです。 - - **Stage**：`emqx` を入力。Snowflake でデータをテーブルにロードする前に保持するステージです。 - - **Pipe**：`emqx` を入力。ステージからテーブルへのロード処理を自動化するパイプです。 - - **Pipe User**：`snowpipeuser` を入力。パイプ管理権限を持つ Snowflake ユーザーです。 - - **Private Key**：RSA プライベートキーのパス（例：`file://`）または RSA プライベートキーファイルの内容を入力します。これは安全な認証に使用され、Snowflake パイプへの安全なアクセスに必要です。ファイルパスを使用する場合は、クラスタ内のすべてのノードでパスが一貫しており、EMQX アプリケーションユーザーがアクセス可能である必要があります。 + - **Database Name**：`testdatabase`。EMQXデータ保存用に作成したSnowflakeデータベース名です。 + - **Schema**：`public`。`testdatabase`内のデータテーブルがあるスキーマ名です。 + - **Stage**：`emqx`。Snowflakeでデータをテーブルにロードする前に保持するステージ名です。 + - **Pipe**：`emqx`。ステージからテーブルへのロードを自動化するパイプ名です。 + - **Pipe User**：`snowpipeuser`。パイプ管理権限を持つSnowflakeユーザー名です。 + - **Private Key**：RSA秘密鍵のパス（例：`file://`）またはRSA秘密鍵ファイルの内容を入力します。これはSnowflakeパイプへの安全なアクセスに必要な認証鍵です。ファイルパスを使用する場合は、クラスター全ノードで同一かつEMQXアプリケーションユーザーがアクセス可能である必要があります。 -8. **Upload Mode** を選択します。現在は `Aggregated Upload` のみサポートしています。この方法は複数のルールトリガー結果を単一ファイル（例：CSV ファイル）にまとめて Snowflake にアップロードし、ファイル数を減らして書き込み効率を向上させます。 +8. **Upload Mode**を選択します。現在は`Aggregated Upload`のみサポートされています。この方式は複数のルールトリガー結果を1つのファイル（例：CSVファイル）にまとめてSnowflakeにアップロードし、ファイル数を減らして書き込み効率を向上させます。 -9. **Aggregation Type** を選択します。現在は `csv` のみサポートしています。データはカンマ区切りの CSV 形式で Snowflake にステージングされます。 +9. **Aggregation Type**を選択します。現在は`csv`のみサポートされており、データはカンマ区切りCSV形式でSnowflakeにステージングされます。 - - **Column Order**：ドロップダウンリストから列の順序を選択します。生成される CSV ファイルは、選択した列の順序でソートされ、未選択の列はアルファベット順にソートされます。 + - **Column Order**：ドロップダウンから列の並び順を選択します。生成されるCSVファイルは選択された列順に並び、未選択列はアルファベット順に続きます。 - - **Max Records**：集約がトリガーされる最大レコード数を設定します。例えば `1000` に設定すると、1000 レコード収集後にアップロードされます。最大レコード数に達すると単一ファイルの集約が完了しアップロードされ、時間間隔がリセットされます。 + - **Max Records**：集約がトリガーされる最大レコード数を設定します。例：`1000`と設定すると1000レコード収集後にアップロードされ、時間間隔がリセットされます。 - - **Time Interval**：集約が行われる時間間隔（秒）を設定します。例えば `60` に設定すると、最大レコード数に達していなくても 60 秒ごとにデータがアップロードされ、最大レコード数がリセットされます。 + - **Time Interval**：集約が行われる時間間隔（秒）を設定します。例：`60`と設定すると最大レコード数に達していなくても60秒ごとにデータがアップロードされ、最大レコード数がリセットされます。 -10. **フォールバックアクション（任意）**：メッセージ配信失敗時の信頼性向上のため、1つ以上のフォールバックアクションを定義できます。これらはプライマリ Sink がメッセージ処理に失敗した場合にトリガーされます。詳細は [Fallback Actions](./data-bridges.md#fallback-actions) を参照してください。 +10. **フォールバックアクション（任意）**：メッセージ配信失敗時の信頼性向上のため、1つ以上のフォールバックアクションを定義できます。詳細は[フォールバックアクション](./data-bridges.md#fallback-actions)を参照してください。 -11. **Advanced Settings** を展開し、必要に応じて詳細設定を行います（任意）。詳細は [Advanced Settings](#advanced-settings) を参照してください。 +11. **詳細設定**を展開し、必要に応じて高度な設定オプションを構成します（任意）。詳細は[詳細設定](#advanced-settings)を参照してください。 -12. 残りの設定はデフォルト値のままにし、**Create** ボタンをクリックして Sink 作成を完了します。作成成功後、ルール作成画面に戻り、新しい Sink がルールアクションに追加されます。 +12. 残りの設定はデフォルト値のままにし、**Create**ボタンをクリックしてSink作成を完了します。作成成功後、ルール作成画面に戻り、新規Sinkがルールアクションに追加されます。 -13. ルール作成画面で **Create** ボタンをクリックし、ルール作成全体を完了します。 +13. ルール作成画面で**Create**ボタンをクリックし、ルール作成全体を完了します。 -これでルールの作成が完了しました。**Rules** ページで新規作成したルールを確認でき、**Actions (Sink)** タブで新しい Snowflake Sink を確認できます。 +これでルールの作成が完了しました。**Rules**ページで新規作成したルールを確認でき、**Actions (Sink)**タブで新しいSnowflake Sinkも確認できます。 -また、**Integration** -> **Flow Designer** をクリックするとトポロジーを視覚的に確認できます。トポロジーは、トピック `t/#` のメッセージがルール `my_rule` によって解析され、Snowflake に書き込まれる流れを示します。 +また、**Integration** -> **Flow Designer**をクリックするとトポロジーが表示されます。トポロジーはトピック`t/#`のメッセージがルール`my_rule`で解析され、Snowflakeに書き込まれる様子を視覚的に示します。 ## ルールのテスト -このセクションでは、設定したルールのテスト方法を示します。 +本節では設定したルールのテスト方法を示します。 ### テストメッセージのパブリッシュ -MQTTX を使ってトピック `t/1` にメッセージをパブリッシュします： +MQTTXを使い、トピック`t/1`にメッセージをパブリッシュします。 ```bash mqttx pub -i emqx_c -t t/1 -m '{ "msg": "Hello Snowflake" }' ``` -この操作を数回繰り返して複数のテストメッセージを生成してください。 +複数回繰り返して複数のテストメッセージを生成してください。 -### Snowflake 内のデータ確認 +### Snowflake内のデータ確認 -テストメッセージ送信後、Snowflake にデータが正常に書き込まれたかを確認します。 +テストメッセージ送信後、Snowflakeにデータが正常に書き込まれたかをSnowflakeインスタンスにアクセスして確認します。 -1. Snowflake のウェブインターフェースを開き、認証情報で Snowflake コンソールにログインします。 +1. SnowflakeのWebインターフェースを開き、認証情報でSnowflakeコンソールにログインします。 -2. Snowflake コンソールで以下の SQL クエリを実行し、ルールによって書き込まれた `emqx` テーブルのデータを表示します： +2. Snowflakeコンソールで以下のSQLクエリを実行し、ルールによって書き込まれた`emqx`テーブルのデータを確認します。 ``` SELECT * FROM testdatabase.public.emqx; ``` - これにより、`emqx` テーブルにアップロードされたすべてのレコードが表示され、`clientid`、`topic`、`payload`、`publish_received_at` フィールドを確認できます。 + これにより、`clientid`、`topic`、`payload`、`publish_received_at`フィールドを含む`emqx`テーブルにアップロードされた全レコードが表示されます。 -3. 送信したテストメッセージ（例：`{ "msg": "Hello Snowflake" }`）や、トピック、タイムスタンプなどのメタデータが確認できるはずです。 +3. 送信したテストメッセージ（例：`{ "msg": "Hello Snowflake" }`）やトピック、タイムスタンプなどのメタデータが確認できるはずです。 ## 詳細設定 -このセクションでは、Snowflake Sink の詳細設定オプションについて説明します。ダッシュボードで Sink を設定する際、**Advanced Settings** を展開して以下のパラメータをニーズに応じて調整できます。 - -| フィールド名 | 説明 | デフォルト値 | -| -------------------------- | ------------------------------------------------------------------------------------------------ | -------------- | -| **Max Retries** | アップロード失敗時の最大リトライ回数を設定します。例えば `3` を入力すると3回までリトライします。 | `3` | -| **Buffer Pool Size** | バッファワーカープロセスの数を指定します。これらのワーカーは EMQX と Snowflake 間のデータフローを管理し、一時的にデータを保持・処理します。パフォーマンス最適化とスムーズなデータ送信に重要です。 | `16` | -| **Request TTL** | リクエストの有効期間（秒）を設定します。リクエストがバッファに入ってからの最大有効時間を指定し、この期間を超えたリクエストは期限切れとみなされます。レスポンスやアックがタイムリーに返らない場合も期限切れとなります。 | | -| **Health Check Interval** | Snowflake との接続の自動ヘルスチェックを行う間隔（秒）を指定します。 | `15` | -| **Max Buffer Queue Size** | Snowflake Sink の各バッファワーカーが保持可能な最大バイト数を指定します。バッファワーカーはデータを一時保管し、効率的にデータストリームを処理します。システム性能やデータ送信要件に応じて調整してください。 | `256` | -| **Query Mode** | リクエストモードを `synchronous` または `asynchronous` から選択し、メッセージ送信を最適化します。非同期モードでは Snowflake への書き込みが MQTT メッセージのパブリッシュをブロックしませんが、クライアントがメッセージ到達前に受信する可能性があります。 | `Asynchronous` | -| **Batch Size** | EMQX から Snowflake へ一度に送信するデータバッチの最大サイズを指定します。サイズ調整によりデータ転送の効率と性能を微調整できます。
`1` に設定すると、データレコードを個別に送信し、バッチ化しません。 | `1` | -| **Inflight Window** | "インフライトキューリクエスト" は開始済みでまだレスポンスやアックを受け取っていないリクエストを指します。この設定は Snowflake との通信中に同時に存在可能なインフライトリクエストの最大数を制御します。
**Request Mode** が `asynchronous` の場合、同一 MQTT クライアントからのメッセージを厳密に順序処理したい場合はこの値を `1` に設定してください。 | `100` | -| **Connect Timeout** | Snowflake への接続試行時のタイムアウト時間（秒）を指定します。例えば `30` 秒に設定すると、その時間内に接続できなければリトライ（**Max Retries** に基づく）またはエラーを発生させます。ネットワークレイテンシや接続信頼性管理に役立ちます。 | `15` | -| **HTTP Pipelining** | レスポンス待ちをせずに送信可能な HTTP リクエストの最大数を指定します。 | `100` | -| **Connection Pool Size** | EMQX が Snowflake に同時に維持可能な接続数を定義します。大きいほど同時リクエスト数が増え高負荷に対応可能ですが、システムリソース消費も増加します。 | `8` | +本節ではSnowflake Sinkの詳細設定オプションについて説明します。ダッシュボードのSink設定画面で**Advanced Settings**を展開し、以下のパラメータをニーズに応じて調整可能です。 + +| 項目名 | 説明 | デフォルト値 | +| ------------------------ | -------------------------------------------------------------------- | ------------ | +| **Max Retries** | アップロード失敗時の最大リトライ回数を設定します。例：`3`で3回までリトライ可能。 | `3` | +| **Buffer Pool Size** | バッファワーカープロセスの数を指定します。これらのワーカーはEMQXとSnowflake間のデータフローを管理し、一時的にデータを保存・処理して送信します。パフォーマンス最適化とスムーズなデータ送信に重要です。 | `16` | +| **Request TTL** | バッファに入ったリクエストが有効とみなされる最大時間（秒）を指定します。TTLを超えるか、送信後にSnowflakeからの応答やアックがタイムリーに得られない場合、リクエストは期限切れと判断されます。 | | +| **Health Check Interval** | SinkがSnowflakeとの接続状態を自動的にヘルスチェックする間隔（秒）を指定します。 | `15` | +| **Max Buffer Queue Size** | 各バッファワーカーがSnowflake Sinkでバッファリング可能な最大バイト数を指定します。バッファワーカーはデータを一時保存し、効率的なデータストリーム処理を担います。システム性能やデータ送信要件に応じて調整してください。 | `256` | +| **Query Mode** | `synchronous`または`asynchronous`のリクエストモードを選択し、メッセージ送信を最適化します。非同期モードではSnowflakeへの書き込みがMQTTメッセージパブリッシュをブロックしませんが、クライアントがSnowflake到着前にメッセージを受信する可能性があります。 | `Asynchronous` | +| **Batch Size** | EMQXからSnowflakeへ一度に送信するデータバッチの最大サイズを指定します。サイズ調整によりデータ転送効率と性能を微調整可能です。
`1`に設定すると、データレコードはバッチ化せず個別に送信されます。 | `1` | +| **Inflight Window** | 送信済みで応答やアックをまだ受け取っていない「インフライトキューリクエスト」の最大数を制御します。
`Request Mode`が`asynchronous`の場合、このパラメータは特に重要です。同一MQTTクライアントからのメッセージを厳密に順序処理したい場合は`1`に設定してください。 | `100` | +| **Connect Timeout** | Snowflakeへの接続試行がタイムアウトするまでの待機時間（秒）を指定します。例：`30`秒。接続できない場合は**Max Retries**に基づきリトライまたはエラーを返します。ネットワークレイテンシや接続信頼性管理に有用です。 | `15` | +| **HTTP Pipelining** | 応答待ち前に送信可能なHTTPリクエストの最大数を指定します。 | `100` | +| **Connection Pool Size** | EMQXがSnowflakeに同時に維持可能な接続数を定義します。大きいほど同時リクエスト数が増え高負荷時に有利ですが、システムリソース消費も増加します。 | `8` | diff --git a/ja_JP/last_translation_commit b/ja_JP/last_translation_commit index f7b95ede3..87e7aac99 100644 --- a/ja_JP/last_translation_commit +++ b/ja_JP/last_translation_commit @@ -1 +1 @@ -c55404f5618e14f7e22283490c620bc71fe5cb6c +95ed1d78eea6125563b1bda5392f0d8d0e6c27b7 diff --git a/ja_JP/observability/opentelemetry/assets/e2e-dashboard-conf-en.png b/ja_JP/observability/opentelemetry/assets/e2e-dashboard-conf-en.png new file mode 100644 index 000000000..119d9bdbd Binary files /dev/null and b/ja_JP/observability/opentelemetry/assets/e2e-dashboard-conf-en.png differ diff --git a/ja_JP/observability/opentelemetry/e2e-traces.md b/ja_JP/observability/opentelemetry/e2e-traces.md index 0f8030741..b05031c3a 100644 --- a/ja_JP/observability/opentelemetry/e2e-traces.md +++ b/ja_JP/observability/opentelemetry/e2e-traces.md @@ -1,102 +1,124 @@ # OpenTelemetryベースのエンドツーエンドMQTTトレーシング -現代の分散システムにおいて、リクエストの流れを追跡しパフォーマンスを分析することは、信頼性と可観測性を確保するために不可欠です。エンドツーエンドトレーシングは、リクエストの開始から終了までの全経路をキャプチャすることを目的とした概念であり、システムの挙動やパフォーマンスに関する深い洞察を得ることができます。 +現代の分散システムにおいて、リクエストの流れを追跡し、パフォーマンスを分析することは、信頼性と可観測性を確保するために不可欠です。エンドツーエンドトレーシングは、リクエストの開始から終了までの全経路をキャプチャすることを目的とした概念であり、システムの挙動やパフォーマンスに関する深い洞察を得ることができます。 -EMQXはバージョン5.8.3以降、MQTTプロトコルに特化したOpenTelemetryベースのエンドツーエンドトレーシング機能を統合しています。この機能により、特にマルチノードクラスター環境において、メッセージのパブリッシュ、ルーティング、配信を明確にトレースできます。これにより、システムパフォーマンスの最適化だけでなく、迅速な障害箇所の特定やシステム信頼性の向上にも役立ちます。 +EMQXはバージョン5.8.3以降、MQTTプロトコルに特化したOpenTelemetryベースのエンドツーエンドトレーシング機能を統合しています。この機能により、特にマルチノードクラスター環境において、メッセージのパブリッシュ、ルーティング、配信の流れを明確にトレースできます。これにより、システムパフォーマンスの最適化だけでなく、迅速な障害箇所の特定やシステムの信頼性向上にも役立ちます。 -本ページでは、MQTTメッセージのフローを包括的に可視化するために、EMQXでエンドツーエンドトレーシング機能を有効化する方法を詳しく解説します。 +本ページでは、EMQXでエンドツーエンドトレーシング機能を有効化し、MQTTメッセージのフローを包括的に可視化する方法を詳しく解説します。 ## OpenTelemetry Collectorのセットアップ 設定の詳細については、[OpenTelemetry Collectorのセットアップ](./traces.md#setting-up-opentelemetry-collector)を参照してください。 -## EMQXでエンドツーエンドトレーシングを有効化する +## EMQXでのエンドツーエンドトレーシングの有効化 ::: tip -エンドツーエンドトレーシングはシステムパフォーマンスに影響を与える可能性があるため、必要な場合のみ有効化してください。 +エンドツーエンドトレーシングはシステムパフォーマンスに影響を与える可能性があるため、必要な場合のみ有効にしてください。 ::: -このセクションでは、EMQXでOpenTelemetryベースのエンドツーエンドトレーシングを有効化する手順と、マルチノード環境でのMQTT分散トレーシング機能のデモを紹介します。 +このセクションでは、EMQXでOpenTelemetryベースのエンドツーエンドトレーシングを有効化する手順を案内し、マルチノード環境でのMQTT分散トレーシング機能を紹介します。 -### ダッシュボードからエンドツーエンドトレーシングを設定する +### ダッシュボードからのエンドツーエンドトレーシング設定 -1. ダッシュボードの左メニューから **Management** -> **Monitoring** をクリックします。 -2. Monitoringページで **Integration** タブを選択します。 -3. 以下の設定を行います： - - **Monitoring platform**: `OpenTelemetry` を選択します。 - - **Feature Selection**: `Traces` を選択します。 - - **Endpoint**: トレースデータのエクスポート先アドレスを設定します。デフォルトは `http://localhost:4317` です。 - - **Enable TLS**: 必要に応じてTLS暗号化を有効にします。通常、本番環境のセキュリティ要件に合わせて設定します。 - - **Trace Mode**: `End-to-End` を選択し、エンドツーエンドトレーシング機能を有効化します。 - - **Cluster Identifier**: span属性に追加するプロパティ値を設定し、どのEMQXクラスターからのデータかを識別できるようにします。プロパティキーは `cluster.id` です。通常はシンプルで識別しやすい名前やクラスター名を設定します。デフォルトは `emqxcl` です。 - - **Traces Export Interval**: トレースデータのエクスポート間隔を秒単位で設定します。デフォルトは `5` 秒です。 - - **Max Queue Size**: トレースデータキューの最大サイズを設定します。デフォルトは `2048` エントリです。 +1. ダッシュボードの左メニューから **Management** -> **Monitoring** をクリックします。 -4. 必要に応じて **Trace Advanced Configuration** をクリックし、詳細設定を行います。 +2. Monitoringページの **Integration** タブを選択します。 - - **Trace Configuration**: クライアント接続やメッセージ送受信、ルールエンジンの実行など、特定イベントのトレース有無を設定できます。 - - **Follow Traceparent**: `traceparent` を追跡するかどうかを設定します。`true` に設定すると、EMQXはクライアントから送信された `User-Property` 内の `traceparent` 識別子を取得し、エンドツーエンドトレーシングに紐付けます。`false` の場合は新規トレースを生成します。デフォルトは `true` です。 - - **Client ID White List**: トレース対象とするクライアント接続やメッセージを制限するホワイトリストを設定できます。不要なトレースを避け、システムリソースの消費を抑制できます。 - - **Topic White List**: トピックのホワイトリストを設定し、マッチするトピックのみをトレース対象とします。クライアントホワイトリストと同様にトレース範囲の制御に役立ちます。 +3. 以下の設定を行います： + - **Monitoring platform**：`OpenTelemetry` を選択します。 - 設定後、**Confirm** をクリックして設定を保存しウィンドウを閉じます。 + - **Feature Selection**：`Traces` を選択します。 + + - **Endpoint**：トレースデータのエクスポート先アドレスを設定します。デフォルトは `http://localhost:4317` です。 + + - **Headers**：トレースエクスポートリクエストにカスタムHTTPヘッダーを追加します。OpenTelemetry Collectorが認証やAPIキー、トークンなどのカスタムヘッダーを必要とする場合に使用します。各ヘッダーはキーと値のペアで指定してください。 + + OpenTelemetry CollectorがBasic認証を使用する場合は、`authorization` ヘッダーに以下の形式で値を設定する必要があります： + + ``` + Key: authorization + Value: Basic dXNlcjpwYXNzd29yZA== + ``` + + これにより、HTTPベースの認証を要求するCollectorとの互換性が向上します。 + + - **Enable TLS**：必要に応じてTLS暗号化を有効にします。通常、本番環境のセキュリティ要件に対応するために使用します。 + + - **Trace Mode**：`End-to-End` を選択し、エンドツーエンドトレーシング機能を有効にします。 + + - **Cluster Identifier**：span属性に追加するプロパティ値を設定し、どのEMQXクラスターからのデータか識別できるようにします。プロパティキーは `cluster.id` です。通常はシンプルで識別しやすい名前やクラスター名を設定します。デフォルトは `emqxcl` です。 + + - **Traces Export Interval**：トレースデータのエクスポート間隔を秒単位で設定します。デフォルトは `5` 秒です。 + + - **Max Queue Size**：トレースデータキューの最大サイズを設定します。デフォルトは `2048` エントリです。 + +4. 必要に応じて **Trace Advanced Configuration** をクリックし、高度な設定を行います。 + + - **Trace Configuration**：クライアント接続やメッセージ送受信、ルールエンジンの実行など、特定のイベントをトレースするかどうかの追加設定を行います。 + - **Follow Traceparent**：`traceparent` を追跡するかどうかを設定します。`true` に設定すると、EMQXはクライアントから送信された `User-Property` 内の `traceparent` 識別子を取得し、エンドツーエンドトレーシングに紐付けます。`false` の場合は新しいトレースを生成します。デフォルトは `true` です。 + - **Client ID White List**：トレース対象とするクライアント接続やメッセージを制限するホワイトリストを設定します。不要なトレースを避け、システムリソースの追加消費を抑制できます。 + - **Topic White List**：トレース対象のトピックを制限するホワイトリストを設定します。クライアントホワイトリストと同様にトレース範囲を制御できます。 + + 設定を保存後、**Confirm** をクリックしてウィンドウを閉じます。 5. **Save Changes** をクリックして設定を保存します。 -OpenTelemetryエンドツーエンドトレーシング ダッシュボード設定画面 +Otel-E2E-Trace-dashboard-page -### 設定ファイルからエンドツーエンドトレーシングを設定する +### 設定ファイルによるエンドツーエンドトレーシング設定 -EMQXがローカルで稼働している前提で、`cluster.hocon` ファイルに以下の設定を追加します。 +EMQXがローカルで動作している前提で、`cluster.hocon` ファイルに以下の設定を追加します。 -設定オプションの詳細は、[EMQXダッシュボード監視統合のOpenTelemetry項目](http://localhost:18083/#/monitoring/integration)を参照してください。 +設定オプションの詳細は、[EMQX Dashboard Monitoring Integration](http://localhost:18083/#/monitoring/integration) のOpenTelemetry節を参照してください。 ```bash opentelemetry { - exporter { endpoint = "http://localhost:4317" } + exporter { + endpoint = "http://localhost:4317" + headers { + authorization = ""Basic dXNlcjpwYXNzd29yZA==" + } + } traces { - enable = true - # エンドツーエンドトレーシングモード - trace_mode = e2e - # エンドツーエンドトレーシングオプション - e2e_tracing_options { - ## クライアント接続/切断イベントをトレース - client_connect_disconnect = true - ## クライアントのサブスクライブ/アンインサブスクライブイベントをトレース - client_subscribe_unsubscribe = true - ## クライアントのメッセージングイベントをトレース - client_messaging = true - ## ルールエンジンの実行をトレース - trace_rule_engine = true - ## クライアントIDホワイトリストの最大長 - clientid_match_rules_max = 30 - ## トピックフィルターホワイトリストの最大長 - topic_match_rules_max = 30 - ## クラスター識別子 - cluster_identifier = emqxcl - ## メッセージトレースレベル（QoS） - msg_trace_level = 2 - ## ホワイトリスト外イベントのサンプリング率 - ## 注：トレースが有効な場合のみサンプリングが適用されます - sample_ratio = "100%" - ## traceparentの追跡 - ## クライアントから渡された`traceparent`をエンドツーエンドトレーシングで追跡するか - follow_traceparent + enable = true + # エンドツーエンドトレーシングモード + trace_mode = e2e + # エンドツーエンドトレーシングオプション + e2e_tracing_options { + ## クライアント接続/切断イベントのトレース + client_connect_disconnect = true + ## クライアントメッセージングイベントのトレース + client_messaging = true + ## クライアントのサブスクライブ/アンザブスクライブイベントのトレース + client_subscribe_unsubscribe = true + ## クライアントIDホワイトリストの最大長 + clientid_match_rules_max = 30 + ## トピックフィルターホワイトリストの最大長 + topic_match_rules_max = 30 + ## クラスター識別子 + cluster_identifier = emqxcl + ## メッセージトレースレベル（QoS） + msg_trace_level = 2 + ## ホワイトリスト外イベントのサンプリング率 + ## 注意：トレース有効時のみ適用 + sample_ratio = "100%" + ## traceparentの追跡 + ## クライアントから渡された`traceparent`をエンドツーエンドトレーシングで追跡するかどうか + follow_traceparent } } max_queue_size = 50000 scheduled_delay = 1000 - } } ``` ## EMQXでのエンドツーエンドトレーシングのデモ -1. EMQXノードを起動します。例として、`emqx@172.19.0.2` と `emqx@172.19.0.3` の2ノードクラスターを起動し、分散トレーシング機能をデモします。 +1. EMQXノードを起動します。例として、`emqx@172.19.0.2` と `emqx@172.19.0.3` の2ノードクラスターを起動し、分散トレーシング機能を確認します。 -2. MQTTX CLIをクライアントとして使用し、異なるノードで同じトピックをサブスクライブします。 +2. MQTTX CLIをクライアントとして使用し、異なるノードで同じトピックにサブスクライブします。 - `emqx@172.19.0.2` ノードでサブスクライブ： @@ -110,9 +132,9 @@ opentelemetry { mqttx sub -t t/1 -h 172.19.0.3 -p 1883 ``` -3. 約5秒後（EMQXのトレースデータエクスポートのデフォルト間隔）、[http://localhost:16686](http://localhost:16686/) のJaeger WEB UIにアクセスし、トレースデータを確認します。 +3. 約5秒後（EMQXのトレースデータエクスポートのデフォルト間隔）、[http://localhost:16686](http://localhost:16686/) のJaeger WEB UIにアクセスしてトレースデータを確認します。 - `emqx` サービスを選択し、**Find Traces** をクリックします。`emqx` サービスがすぐに表示されない場合は、少し待ってページを更新してください。クライアント接続およびサブスクライブイベントのトレースが確認できます： + `emqx` サービスを選択し、**Find Traces** をクリックします。`emqx` サービスがすぐに表示されない場合は、少し待ってページを更新してください。クライアント接続やサブスクライブイベントのトレースが表示されます： ![Jaeger-WEB-UI-e2e-Client-Events](./assets/e2e-client-events.png) @@ -122,36 +144,36 @@ opentelemetry { mqttx pub -t t/1 -h 172.19.0.2 -p 1883 ``` -5. 少し待つと、Jaeger WEB UIでMQTTメッセージの詳細なトレースが確認できます。 +5. 少し待つと、Jaeger WEB UIでMQTTメッセージの詳細なトレースを確認できます。 トレースをクリックすると、詳細なspan情報とトレースタイムラインが表示されます。サブスクライバー数、ノード間のメッセージルーティング、QoSレベル、`msg_trace_level` 設定により、MQTTメッセージのトレースに含まれるspan数は異なります。 - 以下は、2クライアントがQoS 2でサブスクライブし、パブリッシャーがQoS 2のメッセージを送信、`msg_trace_level` が2に設定されている場合のトレースタイムラインとspan情報の例です。 + 以下は、2人のクライアントがQoS 2でサブスクライブし、パブリッシャーがQoS 2のメッセージを送信、`msg_trace_level` が2に設定されている場合のトレースタイムラインとspan情報の例です。 - 特に、クライアント `mqttx_9137a6bb` がパブリッシャーとは異なるEMQXノードに接続しているため、ノード間の送信を表す2つの追加span（`message.forward` と `message.handle_forward`）が表示されています。 + 特に、クライアント `mqttx_9137a6bb` はパブリッシャーとは異なるEMQXノードに接続されているため、ノード間伝送を表す2つの追加span（`message.forward` と `message.handle_forward`）が存在します。 ![Jaeger-WEB-UI-e2e-Message](./assets/e2e-message.png) - また、メッセージやイベントがルールエンジンの実行をトリガーする場合、ルールエンジンのトラッキングオプションが有効であれば、ルールおよびアクションの実行トラッキング情報も取得可能です。 + また、メッセージやイベントがルールエンジンの実行をトリガーする場合、ルールエンジンのトラッキングオプションを有効にすると、ルールおよびアクション実行のトラッキング情報も取得可能です。 ![Jaeger-WEB-UI-e2e-With-Rule-Engine](./assets/e2e-with-rule-engine.png) ::: tip - ルールエンジンの実行を含むエンドツーエンドトレーシング機能は、EMQXバージョン5.9.0以降でサポートされています。 + ルールエンジン実行を含むエンドツーエンドトレーシング機能は、EMQXバージョン5.9.0以降でサポートされています。 ::: ::: warning 重要なお知らせ - この機能は慎重に有効化してください。メッセージやイベントが複数のルールやアクションをトリガーすると、単一のトレースで大量のspanが生成され、システム負荷が増加します。 - メッセージ量やルール・アクション数に応じて適切なサンプリング率を見積もってください。 + この機能は慎重に有効化してください。メッセージやイベントが複数のルールやアクションをトリガーすると、1つのトレースで大量のspanが生成され、システム負荷が増大します。 + メッセージ量やルール・アクション数を考慮し、適切なサンプリング率を見積もってください。 ::: -## トレースspanのオーバーロード管理 +## トレースspanの過負荷管理 -EMQXはトレースspanを蓄積し、定期的にバッチでエクスポートします。エクスポート間隔は `opentelemetry.trace.scheduled_delay` パラメータで制御され、デフォルトは5秒です。バッチトレースspanプロセッサにはオーバーロード保護機能があり、最大蓄積数（デフォルト2048span）を超えると新規spanは破棄されます。以下の設定でこの制限を調整可能です。 +EMQXはトレースspanを蓄積し、定期的にバッチでエクスポートします。エクスポート間隔は `opentelemetry.trace.scheduled_delay` パラメータで制御され、デフォルトは5秒です。バッチトレースspanプロセッサには過負荷保護機能があり、spanの蓄積は上限まで許容されます。デフォルトの上限は2048spanです。この上限は以下の設定で調整可能です。 ```yaml opentelemetry { @@ -162,14 +184,14 @@ opentelemetry { } ``` -`max_queue_size` の上限に達すると、現在のキューがエクスポートされるまで新規トレースspanは破棄されます。 +`max_queue_size` の上限に達すると、新しいトレースspanは現在のキューがエクスポートされるまで破棄されます。 ::: tip 補足 -トレース対象メッセージが多数のサブスクライバーに配信される場合や、メッセージ量が多くサンプリング率が高い場合、オーバーロード保護により多くのspanが破棄され、エクスポートされるspanはごく一部になる可能性があります。 +トレース対象のメッセージが多数のサブスクライバーに配信される場合や、メッセージ量が多くサンプリング率が高い場合、過負荷保護により多くのspanが破棄され、エクスポートされるspanはごく一部になる可能性があります。 -エンドツーエンドトレーシングモードでは、メッセージ量やサンプリング率に応じて `max_queue_size` を増やし、`scheduled_delay` を短縮してspanのエクスポート頻度を上げることを検討してください。これによりオーバーロード保護によるspanの損失を抑制できます。 +エンドツーエンドトレーシングモードでは、メッセージ量やサンプリング率に応じて `max_queue_size` を増加させ、`scheduled_delay` を短縮してspanのエクスポート頻度を上げることを検討してください。これにより過負荷保護によるspanの損失を防げます。 -**ただし、エクスポート頻度の増加やキューサイズの拡大はシステムリソース消費を増加させるため、メッセージTPSや利用可能なシステムリソースを十分に見積もった上で適切に設定してください。** +**ただし、エクスポート頻度の増加やキューサイズの拡大はシステムリソースの消費増加を招くため、メッセージTPSや利用可能なシステムリソースを十分に見積もった上で適切な設定を行ってください。** ::: diff --git a/ja_JP/observability/opentelemetry/logs.md b/ja_JP/observability/opentelemetry/logs.md index c38f0624c..73735daa2 100644 --- a/ja_JP/observability/opentelemetry/logs.md +++ b/ja_JP/observability/opentelemetry/logs.md @@ -1,11 +1,12 @@ -# OpenTelemetryを使ったログ管理の統合 -ファイルログと同様に、OpenTelemetryログは重要なイベント、ステータス情報、エラーメッセージを記録し、開発者や運用チームがアプリケーションの動作を理解しトラブルシューティングを行うのに役立ちます。ただし、OpenTelemetryログは標準化されたログフォーマットを採用しているため、ログの解析や分析、処理が容易です。さらに、Trace ID、タグ、属性などの豊富なコンテキスト情報をログに付加できる点も特徴です。 +# OpenTelemetryを統合したログ管理 -本ページでは、EMQXとOpenTelemetryログハンドラーを統合して高度なログ管理を実現する方法を詳しく解説します。OpenTelemetry Collectorのセットアップ、EMQXでのOpenTelemetryログハンドラーの設定およびログのエクスポート方法、ログ過負荷の管理について説明します。この統合により、EMQXのログイベントを[OpenTelemetryログデータモデル](https://opentelemetry.io/docs/specs/otel/logs/data-model/)に準拠した形式で出力し、設定したOpenTelemetry Collectorやバックエンドにエクスポートできるため、監視やデバッグの効率が向上します。 +ファイルログと同様に、OpenTelemetryログは重要なイベント、ステータス情報、エラーメッセージを記録し、開発者や運用チームがアプリケーションの動作を理解しトラブルシューティングを行うのに役立ちます。ただし、OpenTelemetryログは標準化されたログフォーマットを採用しているため、ログの解析、分析、処理が容易です。さらに、OpenTelemetryログはTrace ID、タグ、属性などの豊富なコンテキスト情報をレコードに追加することをサポートしています。 + +本ページでは、EMQXにOpenTelemetryログハンドラーを統合して高度なログ管理を実現するための包括的なガイドを提供します。OpenTelemetry Collectorのセットアップ、EMQXでのOpenTelemetryログハンドラーの設定およびログのエクスポート、ログ過負荷の管理方法について説明します。この統合により、EMQXのログイベントを[OpenTelemetryログデータモデル](https://opentelemetry.io/docs/specs/otel/logs/data-model/)に準拠した形式でフォーマットし、設定済みのOpenTelemetry Collectorやバックエンドシステムにエクスポートできるようになり、監視とデバッグの機能が向上します。 ## OpenTelemetry Collectorのセットアップ -EMQXのOpenTelemetryログを有効にする前に、OpenTelemetry CollectorおよびOpenTelemetry対応のログ収集システムをデプロイし設定する必要があります。本ガイドでは、[OpenTelemetry Collector](https://opentelemetry.io/docs/collector/getting-started)のデプロイ方法と、debugエクスポーターを使ってログを`stdout`にリダイレクトする設定手順を説明します。 +EMQXでOpenTelemetryログを有効にする前に、OpenTelemetry CollectorおよびOpenTelemetry対応のログ収集システムをデプロイし設定する必要があります。本ガイドでは、[OpenTelemetry Collector](https://opentelemetry.io/docs/collector/getting-started)のデプロイ方法と、デバッグエクスポーターを用いてログを`stdout`にリダイレクトする設定方法を説明します。 1. `otel-logs-collector-config.yaml`という名前でOpenTelemetry Collectorの設定ファイルを作成します。 @@ -34,7 +35,7 @@ EMQXのOpenTelemetryログを有効にする前に、OpenTelemetry Collectorお exporters: [logging] ``` -2. 同じディレクトリにDocker Composeファイル`docker-compose-otel-logs.yaml`を作成します。 +2. 同じディレクトリに、`docker-compose-otel-logs.yaml`というDocker Composeファイルを作成します。 ```yaml version: '3.9' @@ -60,41 +61,45 @@ EMQXのOpenTelemetryログを有効にする前に、OpenTelemetry Collectorお 4. 起動後、OpenTelemetry Collectorは[http://localhost:4317](http://localhost:4317/)でアクセス可能になります。 - ## EMQXでOpenTelemetryログハンドラーを有効化 -1. EMQXの`cluster.hocon`ファイルに以下の設定を追加します（EMQXがローカルで動作している想定です）。 +1. EMQXがローカルで動作していることを前提に、`cluster.hocon`ファイルに以下の設定を追加します。 ```bash opentelemetry { - exporter {endpoint = "http://localhost:4317"} + exporter { + endpoint = "http://localhost:4317" + headers { + authorization = ""Basic dXNlcjpwYXNzd29yZA==" + } + } logs {enable = true, level = warning} } ``` - または、ダッシュボードの **Management** -> **Monitoring** にある **Integration** タブからOpenTelemetryログ統合を設定することも可能です。 + または、ダッシュボードの **Management** -> **Monitoring** に移動し、ページ内の **Integration** タブからOpenTelemetryログ統合を設定することも可能です。 - ::: tip 補足 + ::: tip 注意 - `opentelemetry.logs.level`の設定は、[EMQXログハンドラー](../../observability/log.md)で設定されたデフォルトのログレベルにより上書きされます。例えば、OpenTelemetryのログレベルが`info`でも、EMQXのコンソールログレベルが`error`の場合は、`error`以上のレベルのイベントのみがエクスポートされます。 + `opentelemetry.logs.level`の設定は、[EMQXログハンドラー](../../observability/log.md)で設定されたデフォルトのログレベルによって上書きされます。例えば、OpenTelemetryのログレベルが`info`であっても、EMQXのコンソールログレベルが`error`に設定されている場合、`error`以上のレベルのイベントのみがエクスポートされます。 ::: 2. EMQXノードを起動します。 -3. ダッシュボードからアクセスできないHTTPサービスへのブリッジ作成など、EMQXのログイベントを発生させます。 +3. ダッシュボードからアクセスできないHTTPサービスへのブリッジを作成するなどして、EMQXのログイベントを発生させます。 Otel-logs-HTTP-bridge-example -4. 数秒以内（デフォルトは約1秒）に、Otel CollectorがHTTPブリッジ接続失敗などのEMQXログイベントを受信していることを確認できます。 +4. 数秒以内（デフォルトは約1秒）に、Otel CollectorがHTTPブリッジ接続失敗を示すEMQXログイベントを受信していることを確認できます。 ![Otel-collector-logs-debug-output](./assets/otel-collector-logs-debug-output.png) ## ログ過負荷の管理 -EMQXはログイベントを蓄積し、一定間隔でバッチ処理としてエクスポートします。 -このエクスポートの頻度は`opentelemetry.logs.scheduled_delay`パラメータで制御され、デフォルトは1秒です。 -バッチ処理のログハンドラーは過負荷保護機構を備えており、蓄積できるイベント数に上限を設けています。デフォルトの上限は2048件です。以下の設定でこの上限を変更できます。 +EMQXはログイベントを蓄積し、定期的にバッチでエクスポートします。 +このエクスポート頻度は`opentelemetry.logs.scheduled_delay`パラメータで制御され、デフォルトは1秒です。 +バッチングログハンドラーには過負荷保護機能が組み込まれており、蓄積可能なイベント数の上限が設定されています。デフォルトは2048です。この上限は以下の設定で変更可能です。 ```bash opentelemetry { @@ -104,9 +109,9 @@ opentelemetry { `max_queue_size`の上限に達すると、新しいログイベントは現在のキューがエクスポートされるまで破棄されます。 -::: tip 補足 +::: tip 注意 OpenTelemetryログの過負荷保護は、デフォルトの[EMQXログハンドラー](../log.md)の過負荷保護とは独立して動作します。 -そのため、設定によっては同じログイベントがOpenTelemetryハンドラーで破棄される一方、EMQXのデフォルトログハンドラーでは記録される場合や、その逆もあり得ます。 +そのため、設定によっては同じログイベントがOpenTelemetryハンドラーで破棄される一方、デフォルトのEMQXログハンドラーでは記録される場合や、その逆もあり得ます。 ::: diff --git a/ja_JP/observability/opentelemetry/metrics.md b/ja_JP/observability/opentelemetry/metrics.md index 233044f34..d4c08ff31 100644 --- a/ja_JP/observability/opentelemetry/metrics.md +++ b/ja_JP/observability/opentelemetry/metrics.md @@ -1,11 +1,11 @@ # OpenTelemetryを統合してメトリクスを表示する -EMQXは、gRPC OTELプロトコルを介してメトリクスを直接OpenTelemetry Collectorにプッシュする機能を標準でサポートしています。Collectorはデータを任意のバックエンドにルーティング、フィルタリング、変換し、保存および可視化が可能です。 +EMQXは、gRPC OTELプロトコルを介してメトリクスをOpenTelemetry Collectorに直接プッシュする機能を内蔵しています。Collectorはその後、データを任意のバックエンドにルーティング、フィルタリング、変換し、保存および可視化を行います。 -本ページでは、EMQXとOpenTelemetryの統合方法をダッシュボードを通じて紹介し、[Prometheus](../../observability/prometheus.md)でEMQXのメトリクスを表示する方法を説明します。 +このページでは、Dashboardを通じてEMQXとOpenTelemetryを統合し、[Prometheus](../../observability/prometheus.md)でEMQXのメトリクスを表示する方法を紹介します。 ## 前提条件 -OpenTelemetryとの統合を行う前に、OpenTelemetryとPrometheusをデプロイおよび設定しておく必要があります。 +OpenTelemetryとPrometheusをデプロイおよび設定しておく必要があります。 - [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/getting-started)をデプロイします。 - CollectorのgRPC受信ポート（デフォルトは4317）とPrometheusメトリクスエクスポートポート（8889）を設定します。 @@ -47,13 +47,18 @@ scrape_configs: ## EMQXでOpenTelemetryメトリクスを有効化する -EMQXのOpenTelemetryメトリクス機能との統合は、EMQXダッシュボードまたは設定ファイルで行えます。ダッシュボードでは、左側のナビゲーションメニューから **Management** -> **Monitoring** をクリックし、**Integration** タブでメトリクスの設定を行います。 +EMQX Dashboardまたは設定ファイルを使って、OpenTelemetryメトリクス機能との統合を設定できます。EMQX Dashboardでは、左側のナビゲーションメニューから**Management** -> **Monitoring**をクリックし、**Integration**タブでメトリクスの設定を行います。 -EMQXがローカルで動作している場合、以下の設定をEMQXの `cluster.hocon` ファイルに追加してください。 +EMQXがローカルで動作している場合、以下の設定をEMQXの`cluster.hocon`ファイルに追加してください。 ```bash opentelemetry { - exporter { endpoint = "http://localhost:4317" } + exporter { + endpoint = "http://localhost:4317" + headers { + authorization = ""Basic dXNlcjpwYXNzd29yZA==" + } + } metrics { interval = "10s" } @@ -62,5 +67,5 @@ opentelemetry { ## PrometheusでEMQXメトリクスを可視化する -EMQXのメトリクスは、PrometheusのWebコンソール（http://otel-collector:9090）で確認できます。 +EMQXのメトリクスはPrometheusのWebコンソール（http://otel-collector:9090）で確認できます。 ![OpenTelemetry-Prometheus](./assets/opentelemetry-prometheus.png) diff --git a/ja_JP/observability/opentelemetry/opentelemetry.md b/ja_JP/observability/opentelemetry/opentelemetry.md index e3c32ffb7..56faf52b5 100644 --- a/ja_JP/observability/opentelemetry/opentelemetry.md +++ b/ja_JP/observability/opentelemetry/opentelemetry.md @@ -1,13 +1,17 @@ # OpenTelemetryとの統合 -[OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/)は、トレース、メトリクス、ログなどのテレメトリーデータを生成・管理するためのオブザーバビリティフレームワークおよびツールキットです。重要な点として、OpenTelemetryはベンダーやツールに依存しないため、JaegerやPrometheusなどのオープンソースツールから商用製品まで、幅広いオブザーバビリティバックエンドと連携可能です。 +[OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/)は、トレース、メトリクス、ログなどのテレメトリデータを生成・管理するためのオブザーバビリティフレームワークおよびツールキットです。重要な点として、OpenTelemetryはベンダーやツールに依存しないため、JaegerやPrometheusなどのオープンソースツールから商用製品まで、幅広いオブザーバビリティバックエンドと連携可能です。 -EMQXはgRPC OTELプロトコルを介してOpenTelemetry Collectorへテレメトリーデータを直接プッシュすることをサポートしており、Collectorを通じてデータの転送、フィルタリング、変換を行い、Jaegerや[Prometheus](../../observability/prometheus.md)などの任意のバックエンドに統合して保存・可視化できます。OpenTelemetryとの統合により、EMQXのメトリクス収集、メッセージパブリッシュの分散トレーシング、ログの統合収集およびコンテキスト関連付けが最適化されます。この統合は、EMQXの可視化監視やアラート通知の実現、異なるシステムやサービス間のメッセージフローの追跡に役立ちます。これにより、継続的なパフォーマンス最適化、迅速な問題特定、システム監視が可能となります。 +EMQXはgRPC OTELプロトコルを介してOpenTelemetry Collectorへテレメトリデータを直接プッシュすることをサポートしており、その後Collectorを通じてデータの転送、フィルタリング、変換を行い、Jaegerや[Prometheus](../../observability/prometheus.md)などの任意のバックエンドへ統合して保存・可視化できます。OpenTelemetryとの統合により、EMQXのメトリクス収集、メッセージパブリッシュの分散トレース、ログの統合収集およびコンテキスト関連付けが最適化されます。この統合は、EMQXの可視化監視やアラート通知の実現、異なるシステムやサービス間のメッセージフローの追跡に役立ちます。これにより、継続的なパフォーマンス最適化、迅速な問題の特定、システム監視が容易になります。 emqx-opentelemetry -本セクションでは、EMQXがOpenTelemetry Collectorとテレメトリーデータを統合し、以下のオブザーバビリティ情報に対して完全な組み込みOpenTelemetryサポートを実現する方法を紹介します。 +本セクションでは、EMQXがOpenTelemetry Collectorとテレメトリデータを統合し、以下のオブザーバビリティ情報に対して完全な組み込みOpenTelemetryサポートを実現する方法を紹介します。 - [メトリクス](./metrics.md) - [トレース](./traces.md) - [ログ](./logs.md) + +さらに、EMQXバージョン5.8.3以降では、OpenTelemetryに基づくエンドツーエンドトレースもサポートしています。 + +- [エンドツーエンドトレース](./e2e-traces.md) diff --git a/ja_JP/support/technical-support.md b/ja_JP/support/technical-support.md index b48183941..c4f5c941e 100644 --- a/ja_JP/support/technical-support.md +++ b/ja_JP/support/technical-support.md @@ -1,23 +1,23 @@ --- title: EMQX テクニカルサポート -description: EMQX Enterprise向けの専門的なテクニカルサポートを提供し、堅牢なソリューションとプロフェッショナルな支援でIoTミドルウェアプラットフォームの最適化を支援します。 +description: EMQX Enterprise向けの専門的なテクニカルサポートをご提供し、堅牢なソリューションとプロフェッショナルな支援でIoTミドルウェアプラットフォームの最適化を支援します。 --- # EMQX テクニカルサポート -EMQは、世界をリードするオープンソースIoTデータインフラストラクチャのソフトウェアプロバイダーです。エッジからクラウド、マルチクラウドまでのリアルタイムIoTデータを接続、移動、処理、分析するワンストップのクラウドネイティブ製品を通じて、将来にわたって活用できるIoTアプリケーションの実現を支援しています。 +EMQは、世界をリードするオープンソースIoTデータインフラストラクチャのソフトウェアプロバイダーです。エッジからクラウド、マルチクラウドまで、リアルタイムのIoTデータを接続、移動、処理、分析するワンストップのクラウドネイティブ製品を通じて、将来を見据えたIoTアプリケーションの実現を支援しています。 -当社のコア製品であるEMQXは、世界で最もスケーラブルかつ信頼性の高いオープンソースのMQTTメッセージングプラットフォームであり、1クラスターあたり1億台の同時IoTデバイス接続をサポートし、毎秒100万メッセージのスループットとサブミリ秒のレイテンシを維持します。2万社以上の企業ユーザー、1億台以上のIoTデバイスを接続し、HPE、VMware、Verifone、上汽フォルクスワーゲン、エリクソンなどの著名ブランドを含む400社以上のミッションクリティカルなIoTシナリオで信頼されています。 +当社のコア製品であるEMQXは、世界で最もスケーラブルかつ信頼性の高いオープンソースのMQTTメッセージングプラットフォームであり、1クラスターあたり1億の同時IoTデバイス接続をサポートし、毎秒100万メッセージのスループットとサブミリ秒のレイテンシを維持します。20,000以上の企業ユーザーが利用し、1億以上のIoTデバイスを接続、HPE、VMware、Verifone、SAIC Volkswagen、Ericssonなどの著名ブランドを含む400以上のミッションクリティカルなIoTシナリオで信頼されています。 EMQのグローバルR&Dセンターはストックホルムにあり、アメリカ大陸、ヨーロッパ、アジア太平洋地域に10以上のオフィスを展開しています。 -EMQX製品や当社のIoTソリューションについてご質問がある場合は、以下までお気軽にお問い合わせください。 +EMQX製品や当社のIoTソリューションに関するご質問がございましたら、以下までお気軽にお問い合わせください。 **EMQ** **メール:** [contact@emqx.io](mailto:contact@emqx.io) -**製品フィードバック:** [EMQXサポートポータル](https://www.emqx.com/en/support) +**製品フィードバック:** [EMQX Support Portal](https://www.emqx.com/en/support) **営業:** [sales@emqx.io](mailto:sales@emqx.io) @@ -27,21 +27,21 @@ EMQX製品や当社のIoTソリューションについてご質問がある場 **所在地:** -- 本社：中国 浙江省 杭州市 餘杭区 龍源路88号 3号館 A301 -- グローバルR&Dセンター：スウェーデン ストックホルム Mazarinvägen 36 Sköndal -- ヨーロッパオフィス：ドイツ フランクフルト Eschborner Landstraße 42-50 Haus B, 60489 Frankfurt(M) -- 米国オフィス：1300 El Camino Real, Suite 100, Menlo Park, CA 94025 +- 本社： 中国 浙江省 杭州市 余杭区 龍源路88号 3号棟 A301 +- グローバルR&Dセンター： スウェーデン ストックホルム Mazarinvägen 36 Sköndal +- ヨーロッパオフィス： ドイツ フランクフルト Eschborner Landstraße 42-50 Haus B, 60489 Frankfurt(M) +- 米国オフィス： 1300 El Camino Real, Suite 100, Menlo Park, CA 94025 -EMQXサービスチームは、専門的なサポートを提供いたします。 +EMQXサービスチームは、専門的なサポートを提供いたします： -- IoTソリューションの設計、デプロイメント、カスタマイズに関する専門的なサポートは、[EMQXサービスチーム](https://www.emqx.com/en/contact?product=emqx)までご連絡ください。 -- 提供している商用サポート内容については、[EMQXサポートポータル](https://www.emqx.com/en/support)をご覧ください。 +- IoTソリューションの設計、デプロイ、カスタマイズに関する専門的なサポートは、[EMQXサービスチーム](https://www.emqx.com/en/contact?product=emqx)までご連絡ください。 +- 当社が提供する商用サポートの詳細は、[EMQX Support Portal](https://www.emqx.com/en/support)をご覧ください。 **商用サポートレベル** | 機能 | スタンダード | プロフェッショナル | | -------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- | -| サポート時間 | 平日5日8時間 | 24時間365日 | +| サポート時間 | 5*8 | 7*24 | | メールサポート | support | support | | オンラインチャットサポート | support | support | | 電話ホットラインサポート | no support | support | @@ -49,15 +49,14 @@ EMQXサービスチームは、専門的なサポートを提供いたします | 緊急バグ修正 | no support | support | | サードパーティプラグインサポート | no support | support | -EMQXの開発者やユーザーの皆様は、EMQXフォーラム、Slackチャンネル、GitHubページにぜひご参加ください。質問の投稿、回答の検索、アイデアやベストプラクティスの共有が可能です。 +EMQXの開発者やユーザーの皆様は、EMQXフォーラムやSlackチャンネル、GitHubページに参加して、質問したり、回答を見つけたり、アイデアやベストプラクティスを共有したりできます： -- [EMQXフォーラム](https://www.emqx.io/forum/)：EMQXに関する質問を投稿できます。 -- [Slack](https://slack-invite.emqx.io/)：世界中のEMQX開発者やユーザーとつながれます。 -- [GitHub](https://github.com/emqx/emqx)：EMQXのコード取得、問題報告、新機能リクエストが可能です。 +- [Slack](https://slack-invite.emqx.io/)：世界中のEMQX開発者およびユーザーとつながることができます。 +- [GitHub](https://github.com/emqx/emqx)：EMQXのソースコードの閲覧、問題報告、新機能のリクエストが可能です。 -また、以下のSNSでも情報発信を行っています。 +また、以下でもご連絡いただけます： -- [Twitter](https://twitter.com/EMQTech) +- [X](https://x.com/EMQTech) - [YouTube](https://www.youtube.com/channel/UC5FjR77ErAxvZENEWzQaO5Q) - [LinkedIn](https://www.linkedin.com/company/emqtech) - [Discord](https://discord.com/invite/xYGf3fQnES)