diff --git a/ja_JP/changes/all-changes-ee.md b/ja_JP/changes/all-changes-ee.md index 5fdfe1a9c..9812a4e57 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 @@ -63,6 +65,13 @@ EMQX Enterprise のリリースノートページでは、各バージョンに ## v4.4 +- [4.4.30](./changes-ee-v4.md#_4-4-30): 2025-06-20 +- [4.4.29](./changes-ee-v4.md#_4-4-29): 2025-03-07 +- [4.4.28](./changes-ee-v4.md#_4-4-28): 2025-01-23 +- [4.4.27](./changes-ee-v4.md#_4-4-27): 2024-11-28 +- [4.4.26](./changes-ee-v4.md#_4-4-26): 2024-09-26 +- [4.4.25](./changes-ee-v4.md#_4-4-25): 2024-09-13 +- [4.4.24](./changes-ee-v4.md#_4-4-24): 2024-04-16 - [4.4.23](./changes-ee-v4.md#_4-4-23): 2023-11-24 - [4.4.22](./changes-ee-v4.md#_4-4-22): 2023-11-01 - [4.4.21](./changes-ee-v4.md#_4-4-21): 2023-10-16 diff --git a/ja_JP/changes/changes-ee-v4.md b/ja_JP/changes/changes-ee-v4.md index 541e2392a..b51410c49 100644 --- a/ja_JP/changes/changes-ee-v4.md +++ b/ja_JP/changes/changes-ee-v4.md @@ -1,5 +1,157 @@ # EMQX Enterprise Version 4 +## e4.4.30 + +*Release Date: 2025-06-20* + +### Enhancements + +- Smoother global garbage collection. + + EMQX periodically performs garbage collection on all processes, with the interval controlled by the `node.global_gc_interval` setting (default: 15 minutes). This mechanism helps prevent situations where the Erlang VM's default garbage collection fails to reclaim off-heap binary memory in time under extreme conditions. However, this can cause noticeable periodic spikes in CPU usage. + + The new global garbage collection mechanism performs garbage collection on processes in batches during each cycle, reducing fluctuations in CPU usage. This optimization only takes effect when `node.global_gc_interval` is set to more than one minute. + +### Bug Fixes + +- Fixed an issue where some connections would be disconnected when hot upgrading from older versions to 4.4.28 or 4.4.29. The number of disconnected clients is positively correlated with the message rate on the current node. + + +## e4.4.29 + +*Release Date: 2025-03-07* + +### Enhancements + +- Optimized License check performance. + + This optimization reduces the performance overhead of checking the total number of connections against the License when clients establish connections by minimizing inter-node RPC calls. + +- Improved connection management during mass client reconnections to prevent connection rejections due to License limits. + + After this optimization, even if the current connection count exceeds the License limit, EMQX will still allow clients with an already established ClientID to reconnect. + +- Enhanced Wolff to support Kafka topics being rebuilt with fewer partitions. + + Previously, Wolff (EMQX’s Kafka driver) only supported increasing the number of partitions in a Kafka topic (scaling up) but did not support reducing partitions (scaling down). + + Since Kafka does not allow direct partition reduction, users typically need to create a new topic and migrate data, or delete the old topic and create a new one with the same name if data loss is acceptable. Before this improvement, Wolff could not handle such cases correctly, potentially causing some producers to fail to reconnect. + +- Unified default values for the `acceptors` and `max_connections` settings across all listeners. + + After the improvement, the default value for the `acceptors` setting is unified to 16 across all listener types, and the default value for `max_connections` is 1,024,000. + +- Expanded configuration options for the Trace module. + + The Trace module now supports three new options: + + - **Line Max Size:** Controls the maximum number of characters per line in the log file (default: `2048`). + - **File Max Size:** Sets the maximum size of a log file (default: `1GB`). + - **Client Process Max Heap Size:** The default value is `512MB`, which helps prevent client connection processes from being terminated due to low default memory limits (64MB on 64-bit systems) when log tracing is enabled. + +- Added a Warning log when a client process is terminated. + + Previously, when a client process was terminated due to memory constraints, the only available log was an Erlang/OTP error message, which did not specify which client was affected: + + ``` + [error] Process: <0.3540.0> on node 'emqx@127.0.0.1', Context: maximum heap size reached, Max Heap Size: 167772160, Total Heap Size: 200934817, Kill: true, ... + ``` + + Now, EMQX adds a Warning log alongside this message to help users identify the affected client: + + ``` + [warning] [CM] Clean down, clientid: abcd_bench_pub_1, pid: <0.3540.0>, reason: killed + ``` + +### Bug Fixes + +- Fixed an issue where EMQX deployed in containers could not update the `acceptors` and `max_connections` settings using the hot configuration feature. + +- Fixed an issue where EMQX might fail to reconnect to Redis after a master-slave switch in Redis Cluster mode. + + Previously, if EMQX could not connect to the new Redis master node after a failover due to network issues, `eredis_cluster` (EMQX’s Redis Cluster driver) would enter an abnormal state, preventing it from reconnecting to Redis properly. + +- Fixed an occasional unresponsiveness issue when downloading log tracing files from the Dashboard. + +- Fixed a packet parsing issue in the Pulsar driver. + +## e4.4.28 + +*Release Date: 2025-01-23* + +### Enhancements + +- Improved the self-healing capability of the EMQX cluster. + + Previously, EMQX could only self-heal simple split-brain scenarios, but not others: + + - When one node can maintain contact with all other nodes, it is used as the base node, and other nodes are restarted to restore the cluster. + - When the split-brain forms two sub-clusters, the sub-cluster with fewer nodes is restarted to restore the cluster. + + After the improvement, even if the split-brain becomes multiple complex and asymmetric clusters, EMQX can still self-heal. + +- Optimized the performance of handling wildcard subscriptions and un-subscriptions in EMQX. + + This improvement changes the prefix tree table from a `mnesia` table that needs to be replicated between nodes to an `ETS` table, eliminating the time spent synchronizing prefix tree information between nodes. After the improvement, EMQX's subscription handling is **asynchronous**: + + 1. First, EMQX updates the prefix tree and routing records locally and replies with SUBACK. + 2. The routing information is asynchronously updated to other nodes, which then update their own prefix trees. + + This optimization will significantly improve the performance of handling subscriptions and un-subscriptions in EMQX, especially when there are many nodes and high network latency between nodes. + + Note that if there are older versions of EMQX nodes in the cluster, wildcard subscriptions added on the older nodes can be correctly established on the new version nodes, but not vice versa. This means that during a rolling upgrade, wildcard subscriptions made on newly upgraded nodes may not receive messages from older nodes. This issue is automatically resolved once all nodes are upgraded. After a node is upgraded, the prefix tree will be rebuilt through the routing table, so routing information will not be lost during the rolling upgrade. + +- Optimized the matching performance of the rule engine. + + This optimization improves the matching performance of the rule engine by caching the topic prefix tree and removing excessive topic splitting operations. This optimization is more significant in scenarios with many rules. + +- Added a "Buffer Max Linger Time" option to the Kafka action. + + This option controls the maximum wait time for the producer to collect messages for each partition before writing them to the buffer in batches. The default value of `0ms` means no waiting. For non-memory buffering modes, it is recommended to set at least `5ms` to reduce IOPS. + +- Changed the handling of alarms to asynchronous mode. + + Previously, alarms were handled synchronously, and a large number of `conn_congestion` alarms could affect the MQTT connection process. Now, alarms are handled asynchronously, and overload protection has been added. When the alarm system is overloaded, alarms will enter a "silent period" of one minute, during which any alarms will be discarded. + +- Added monitoring and alarming for process message queue length. + + Two new configuration items `vm_mon.process_long_msgq` and `vm_mon.process_alarm_top_n` have been added to control the monitoring and alarming of process message queue length. + + - `vm_mon.process_long_msgq`: Triggers an alarm when the mailbox of a process in EMQX exceeds this length, with a default value of `80`. + - `vm_mon.process_alarm_top_n`: When an alarm is triggered, include the information of the top N processes with the longest non-zero message queues in the alarm. The default value is `5`. + +- Optimized the logging of CONNECT packet parsing failures. + + After the improvement, if an MQTT connection is disconnected due to a failure in parsing the CONNECT variable header, `esockd` will no longer log such errors, and the disconnection reason will be marked as: `malformed_connect_variable_header`: + + ``` + [error] supervisor: 'esockd_connection_sup - <0.5949.0>', errorContext: connection_shutdown, reason: {badmatch,<<>>}, offender: [{pid,<0.13949.4720>}, ...] + ``` + +- Changed the log to "Always Asynchronous" mode. + + Previously, the default value of the `log.sync_mode_qlen` configuration was 100, meaning that when the log queue length exceeded 100, the log would switch to synchronous mode. This has been changed to 3000, consistent with the default value of `log.drop_mode_qlen`, so that the log handler always works in asynchronous mode and starts discarding logs when the queue length exceeds 3000. + +- Optimized the performance of slow subscriptions. + + This optimization slightly reduces the performance overhead of the slow subscription feature by avoiding calling `ets:info(emqx_slow_subs_topk, size)`. + +- Reduced the time spent updating listeners through hot configuration. + + Previously, when updating listener configurations through hot configuration, EMQX would sequentially update and restart listeners on each node, which could take a long time when there were many connections. Now, by using `erpc:multicall/4`, EMQX will update listeners on each node in parallel, reducing the time spent. + +- Avoid blocking `ecpool_sup` by slow-starting `ecpool_worker`. + +### Bug Fixes + +- Fixed an issue where the username of a persistent session would disappear from the username quota page. + + Before the fix, the username of a persistent session's MQTT client would disappear from the username quota page after reconnecting. + +- Fixed a performance degradation issue caused by log throttling. + + Before the fix, due to issues in the log throttling feature, enabling log tracing would significantly increase EMQX's resource consumption. + ## 4.4.27 *Release Date: 2024-11-28* 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..6525387f8 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) -稼働中の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) を使ってパスワード有効期限を設定可能です。 **例**: @@ -86,12 +125,12 @@ curl -X 'PUT' \ ### アカウントロックと解除 -セキュリティ強化のため、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..63df591ce 100644 --- a/ja_JP/data-integration/data-bridge-rocketmq.md +++ b/ja_JP/data-integration/data-bridge-rocketmq.md @@ -1,52 +1,52 @@ -# Bridge MQTT Data into RocketMQ +# RocketMQへのMQTTデータブリッジ -EMQXは[RocketMQ](https://rocketmq.apache.org/)へのデータブリッジをサポートしており、MQTTメッセージやクライアントイベントをRocketMQに転送できます。例えば、RocketMQを使ってデバイスからのセンサーデータやログデータを収集することが可能です。 +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にシームレスに書き込まれます。 +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データ連携は同期・非同期の両書き込みモードをサポートし、シナリオに応じてレイテンシとスループットのバランスを柔軟に調整可能です。 +- **MQTTメッセージの変換**：ルールエンジンを用いて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 @@ -137,32 +137,32 @@ Linux環境では、`host.docker.internal`を実際のIPアドレスに変更し ## コネクターの作成 -このセクションでは、SinkをRocketMQサーバーに接続するためのコネクター作成方法を説明します。 +本節では、SinkをRocketMQサーバーに接続するためのコネクター作成方法を説明します。 -以下の手順は、EMQXとRocketMQをローカルマシンで実行している場合を想定しています。リモートで実行している場合は設定を適宜調整してください。 +以下の手順は、EMQXとRocketMQの両方をローカルマシンで実行している場合を想定しています。リモート環境で実行している場合は設定を適宜調整してください。 -1. EMQXダッシュボードに入り、**Integration** -> **Connectors**をクリックします。 +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)を参照してください。 + - **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,19 +175,19 @@ 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**はデフォルトで空欄のままにします。 @@ -199,23 +199,23 @@ Linux環境では、`host.docker.internal`を実際のIPアドレスに変更し 10. **Fallback Actions（任意）**：メッセージ配信失敗時の信頼性向上のため、1つ以上のフォールバックアクションを定義できます。詳細は[Fallback Actions](./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ルール文は以下の通りです： @@ -228,7 +228,7 @@ FROM ::: tip -便宜上、オンライン／オフラインイベントの受信用に`TopicTest`トピックを再利用します。 +便宜上、オンライン／オフラインイベントの受け取りに`TopicTest`トピックを再利用します。 ::: @@ -244,7 +244,7 @@ Sinkの稼働状況を確認すると、新規の受信メッセージと送信 データが`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..67839c17f 100644 --- a/ja_JP/data-integration/rule-sql-builtin-functions.md +++ b/ja_JP/data-integration/rule-sql-builtin-functions.md @@ -18,20 +18,20 @@ - [システム関数](#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)をご参照ください。 ::: @@ -41,7 +41,7 @@ EMQXは幅広い数学関数をサポートしています： - 三角関数および双曲線関数：sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh - 数値関数：abs, ceil, floor, round, sqrt, fmod -- 指数関数および対数関数：exp, power, log, log10, log2 +- 指数・対数関数：exp, power, log, log10, log2 ### abs(X: integer | float) -> integer | float @@ -54,7 +54,7 @@ abs(-1.2) = 1.2 ### acos(X: integer | float) -> float -`X` のアークコサイン（ラジアン単位）を返します。`X` の範囲は `[-1, 1]` です。例： +`X` のアークコサインをラジアンで返します。`X` の範囲は `[-1, 1]` です。例： ```bash acos(0.5) = 1.0471975511965976 @@ -62,7 +62,7 @@ acos(0.5) = 1.0471975511965976 ### acosh(X: integer | float) -> float -`X` の双曲線アークコサイン（ラジアン単位）を返します。`X` は1以上でなければなりません。例： +`X` の双曲線アークコサインをラジアンで返します。`X` は1以上でなければなりません。例： ```bash acosh(1.5) = 0.9624236501192069 @@ -70,7 +70,7 @@ acosh(1.5) = 0.9624236501192069 ### asin(X: integer | float) -> float -`X` のアークサイン（ラジアン単位）を返します。`X` の範囲は `[-1, 1]` です。例： +`X` のアークサインをラジアンで返します。`X` の範囲は `[-1, 1]` です。例： ```bash asin(0.5) = 0.5235987755982988 @@ -86,7 +86,7 @@ asinh(0.5) = 0.48121182505960347 ### atan(X: integer | float) -> float -`X` のアークタンジェント（ラジアン単位）を返します。例： +`X` のアークタンジェントをラジアンで返します。例： ```bash atan(0.5) = 0.46364760900080615 @@ -110,7 +110,7 @@ ceil(0.8) = 1 ### cos(X: integer | float) -> float -角度 `X`（ラジアン単位）のコサインを返します。例： +角度 `X`（ラジアン）のコサインを返します。例： ```bash cos(0.5) = 0.8775825618903728 @@ -126,7 +126,7 @@ cosh(0.5) = 1.1276259652063807 ### exp(X: integer | float) -> float -自然対数の底 `e` の `X` 乗を返します。例： +自然対数の底 e の `X` 乗を返します。例： ```bash exp(1) = 2.718281828459045 @@ -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 @@ -199,7 +199,7 @@ random() = 0.5400050092601868 ### sin(X: integer | float) -> float -角度 `X`（ラジアン単位）のサインを返します。例： +角度 `X`（ラジアン）のサインを返します。例： ```bash sin(0.5) = 0.479425538604203 @@ -223,7 +223,7 @@ sqrt(9) = 3.0 ### tan(X: integer | float) -> float -角度 `X`（ラジアン単位）のタンジェントを返します。例： +角度 `X`（ラジアン）のタンジェントを返します。例： ```bash tan(0.5) = 0.5463024898437905 @@ -239,7 +239,7 @@ tanh(0.5) = 0.46211715726000974 ## データ型判定関数 -指定したフィールドのデータ型を判定し、指定したデータ型に合致するかどうかを真偽値で返します。 +指定したフィールドのデータ型を判定し、指定の型に合致するかどうかを真偽値で返します。 ### is_array(Term: any) -> boolean @@ -292,8 +292,7 @@ is_map(json_decode('[{"value": 1}]')) = false ### is_null(Term: any) -> boolean -変数 `Term` が未定義か判定します。 -この関数は変数に値が割り当てられているかを判定するために使い、値がJSONの `null` であっても未定義とはみなしません。 +変数 `Term` が未定義か判定します。値がJSONの `null` であっても割り当て済みとみなされます。 例： @@ -315,7 +314,7 @@ 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 @@ -338,7 +337,7 @@ is_str(123) = false ### is_empty(Array or Map) -> boolean -配列またはマップが空か判定します。例： +`Array` または `Map` が空か判定します。例： ```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桁の有効数字をサポートします。文字列 `Term` が表す浮動小数点数の有効数字が16桁を超える場合、変換時に丸め誤差が発生する可能性があります。 例： @@ -391,7 +390,7 @@ 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 @@ -400,9 +399,9 @@ float('0.000012345', 5) = 0.00001 ### float2str(Float: float, Decimals: integer) -> string -浮動小数点数 `Float` を文字列に変換します。小数点以下最大 `Decimals` 桁まで含み、末尾のゼロは切り捨てられます。`Decimals` の範囲は `[0, 253]` です。`Float` の有効数字が16桁を超える場合、変換時に丸め誤差が発生する可能性があります。 +浮動小数点数 `Float` を文字列に変換します。小数点以下最大 `Decimals` 桁まで表示し、末尾のゼロは切り捨てます。`Decimals` の範囲は `[0, 253]` です。`Float` の有効数字が16桁を超える場合、変換時に丸め誤差が発生する可能性があります。 -浮動小数点数はコンピュータ上で正確に保存できないため、`Decimals` が `Float` の小数点以下の桁数（先行ゼロ含む）を超える場合、`float2str` は `Float` の2進近似値の10進表現を返すことがあります。 +浮動小数点数はコンピューター上で正確に保存できないため、`Decimals` が `Float` の小数点以下桁数（先行ゼロ含む）より大きい場合、`float2str` は `Float` の2進近似の10進表現を返すことがあります。 例： @@ -424,9 +423,9 @@ float2str(123456789.01234566, 8) = '123456789.01234566' `Term` を整数に変換します。 -- `Term` がブール型の場合、trueは1、falseは0に変換されます。 +- `Term` がブール型の場合、`true` は1、`false` は0に変換されます。 - `Term` が浮動小数点型の場合、`Term` 以下の最大の整数に切り捨てられます。 -- `Term` が文字列の場合、少なくとも1つの数字を含み、先頭に `+` または `-` の1文字の接頭辞が付くことができ、先行ゼロは無視されます。数学的表記もサポートします。 +- `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,9 @@ int('Number 100') 任意の型の `Term` を文字列に変換します。 -- `Term` がマップまたは配列の場合、`str` 関数は `Term` をJSONエンコードしようとします。 -- `Term` が浮動小数点数の場合、末尾のゼロを切り捨てた対応する文字列を返します。戻り値の文字列は小数点以下最大10桁まで保持します。より多くの小数桁を返すには `float2str` 関数を使用してください。 +`Term` がマップまたは配列の場合、`str` 関数は `Term` をJSONエンコードしようとします。 + +`Term` が浮動小数点数の場合、末尾のゼロを切り捨てた対応する文字列を返します。返される文字列は小数点以下最大10桁まで保持します。より多くの小数桁を返すには `float2str` 関数を使用してください。 例： @@ -463,11 +463,12 @@ 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桁目以降で丸め str(3.14159265359) = '3.1415926536' str(0.000000314159265359) = '0.0000003142' ``` @@ -476,7 +477,7 @@ str(0.000000314159265359) = '0.0000003142' 任意の `Term` をUTF-8エンコードされた文字列に変換します。 -動作は `str(Any)` と同一です。 +その他の挙動は `str(Any)` と同じです。 ```bash str_utf8(100) = '100' @@ -485,28 +486,29 @@ 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桁目以降で丸め 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コードを返します。複数文字の場合は最初の文字のコードのみ返します。例： ```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, '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' @@ -562,7 +562,7 @@ find('Front, Middle, End', ', ', 'trailing') = ', End' ### join_to_string(Sep: string, Array: array) -> string -配列 `Array` の要素を区切り文字 `Sep` で連結して1つの文字列にします。例： +`Array` の要素を区切り文字 `Sep` で連結して1つの文字列にします。例： ```bash join_to_string(', ', ['a', 'b', 'c']) = 'a, b, c' @@ -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` 指定時、埋めるスペース数が奇数の場合は末尾に多く埋めます。 例： @@ -611,7 +611,7 @@ pad('hello', 8, 'both') = ' hello ' `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,9 +673,9 @@ replace('ab..cd..ef', '..', '') = 'abcdef' `Where` の値は以下の通りです： -- `all`: すべての `SearchPattern` を置換（`replace/3` と同等） -- `leading`: 先頭の `SearchPattern` のみ置換 -- `trailing`: 末尾の `SearchPattern` のみ置換 +- `all`: すべて置換（`replace/3` と同等） +- `leading`: 先頭の1回のみ置換 +- `trailing`: 末尾の1回のみ置換 例： @@ -693,7 +695,7 @@ reverse('hello') = 'olleh' ### rm_prefix(String: string, Prefix: string) -> string -文字列 `String` の先頭にある `Prefix` を削除します。`String` が `Prefix` で始まらない場合は元の文字列を返します。例： +文字列 `String` の先頭から `Prefix` を削除します。`String` が `Prefix` で始まらない場合は元の文字列を返します。例： ```bash rm_prefix('foo/bar', 'foo/') = 'bar' @@ -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,18 +726,18 @@ 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`: 文字列内のすべての区切り文字を処理し、空文字列を含む可能性あり +- `notrim`: 文字列中のすべての区切り文字を処理し、空文字列を含む可能性あり - `leading`: 先頭の区切り文字のみ処理し、空文字列は含まない - `leading_notrim`: 先頭の区切り文字のみ処理し、空文字列を含む可能性あり - `trailing`: 末尾の区切り文字のみ処理し、空文字列は含まない @@ -753,11 +755,11 @@ split('a;b;c;', ';', 'trailing_notrim') = ['a;b;c', ''] ### sprintf(Format, ...) -> string -`Format` に従ってフォーマットされた文字列を返します。`Format` 文字列は通常の文字とフォーマット用制御シーケンスを含みます。 +`Format` に従いフォーマットされた文字列を返します。`Format` 文字列は通常文字とフォーマット制御シーケンスを含みます。 -制御シーケンスの形式は一般的に `~F.P.PadModC` です。 +制御シーケンスの形式は一般に `~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` 位置から最大 `Length` 文字の部分文字列を返します。添字は0始まりです。例： ```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 { @@ -857,13 +859,13 @@ SELECT split(payload, '\n') as device_info FROM 't/#' } ``` -`unescape` 関数で `\n` をアンエスケープすると期待通りの結果が得られます： +`unescape` 関数でアンエスケープすると期待通りの結果が得られます： ```sql SELECT split(payload, unescape('\n')) as device_info FROM 't/#' ``` -出力結果： +出力： ```json { @@ -884,7 +886,7 @@ SELECT split(payload, unescape('\n')) as device_info FROM 't/#' - `\t`：水平タブ（HT） - `\r`：復帰（CR） - `\b`：バックスペース（BS） - - `\f`：改ページ（FF） + - `\f`：フォームフィード（FF） - `\v`：垂直タブ（VT） - `\'`：シングルクォート（'） - `\"`：ダブルクォート（"） @@ -894,13 +896,13 @@ SELECT split(payload, unescape('\n')) as device_info FROM 't/#' - 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 @@ -953,9 +955,9 @@ map_get('a', map_put('a', 2, json_decode('{"a": 1}'))) = 2 マップを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` のようになります。マップのフィールド順序は非決定的です。 +例えば、`payload.value` が `{"a" : 1, "b": 2}` の場合、生成されるコマンドは `HMSET name1 b 2 a 1` となります。マップのフィールド順序は非決定的です。 ### map_to_entries(Map: map) -> array @@ -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 @@ -994,7 +996,7 @@ mget(['a', 'b'], mput(['a', 'b'], 2, json_decode('{"c": 1}'))) = 2 ### map_size(Map: map) -> any -`Map` のキーの数を返します。例： +`Map` のキー数を返します。例： ```bash map_size(json_decode('{}')) = 0 @@ -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([]) ``` @@ -1050,20 +1052,20 @@ length([]) = 0 ### nth(N: integer, Array: array) -> any -配列 `Array` のN番目の要素を返します。`N` は配列の長さを超えてはいけません。例： +配列 `Array` のN番目の要素を返します。`N` は配列長以下でなければなりません。例： ```bash # 正しい例 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エンコードできないため、16進数文字列に変換するには `bin2hexstr` 関数を使用してください。 ### gunzip(Data: binary) -> binary | string @@ -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` のビットごとの否定（NOT）演算結果を返します。入力・出力は符号付き整数です。例： ```bash bitnot(10) = -11 @@ -1184,7 +1186,7 @@ bitnot(-12) = 11 ### bitsl(Num: integer, Shift: integer) -> integer -`Num` を左に `Shift` ビットシフトし、右端を0で埋めます。例： +`Num` をビット単位で左に `Shift` ビットシフトし、右端を0で埋めます。例： ```bash bitsl(8, 2) = 32 @@ -1193,7 +1195,7 @@ bitsl(-8, 2) = -32 ### bitsr(Num: integer, Shift: integer) -> integer -`Num` を右に `Shift` ビットシフトし、左端を符号ビットで埋めます（正数は0、負数は1）。例： +`Num` をビット単位で右に `Shift` ビットシフトし、左端を符号ビットで埋めます（正数は0、負数は1）。例： ```bash bitsr(8, 2) = 2 @@ -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,15 @@ 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など外部形式に直接シリアライズできません。通常は整数などに変換する前の中間値として使われます。 ::: @@ -1289,20 +1290,23 @@ 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` に変換します。 +バイト列 `Bin` の位置 `Start`（1始まり）から長さ `BitNum` のビットを抽出し、指定したバイト順 `Endianness` と符号属性 `Signedness` に従い、指定の型 `OutputType` に変換します。 + +`OutputType` の値： + +- bits（bitstringの略） +- integer +- float + +`Signedness` の値： -- `OutputType` の可能な値： - - bits（bitstringの略） - - integer - - float +- signed +- unsigned -- `Signedness` の可能な値： - - signed - - unsigned +`Endianness` の値： -- `Endianness` の可能な値： - - big - - little +- big +- little `OutputType` が `float` の場合、`Signedness` は無効です。`OutputType` が `bits` の場合、`Signedness` と `Endianness` は無効です。 @@ -1324,7 +1328,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 +1337,7 @@ bin2hexstr(base64_decode('y0jN')) = 'CB48CD' ### base64_encode(Data: binary | string) -> string -`Data` をBase64形式にエンコードします。例： +`Data` をbase64形式にエンコードします。例： ```bash base64_encode('hello') = 'aGVsbG8=' @@ -1358,7 +1362,7 @@ json_encode([1,2,3]) = '[1,2,3]' ### bin2hexstr(Data: binary) -> string -バイナリデータを対応する16進文字列に変換します。例： +バイナリデータを対応する16進数文字列に変換します。例： ```bash bin2hexstr(zip('hello')) = 'CB48CDC9C90700' @@ -1366,7 +1370,7 @@ bin2hexstr(zip('hello')) = 'CB48CDC9C90700' ### hexstr2bin(Data: string) -> binary -16進文字列を対応するバイナリデータに変換します。例： +16進数文字列を対応するバイナリデータに変換します。例： ```bash unzip(hexstr2bin('CB48CDC9C90700')) = 'hello' @@ -1374,11 +1378,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 +1394,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 @@ -1410,7 +1414,7 @@ EMQXは `schema_encode` と `schema_decode` 関数を使い、指定したスキ ### **Sparkplug B関数** -EMQXはSparkplug Bメッセージのデコード・エンコード用の特殊関数（`sparkplug_decode` と `sparkplug_encode`）も備えています。詳細は [Sparkplug B](./sparkplug.md) を参照してください。 +EMQXはSparkplug Bメッセージのデコード・エンコード用に特別な関数（`sparkplug_decode` と `sparkplug_encode`）も備えています。詳細は[Sparkplug B](./sparkplug.md)をご覧ください。 ## 日時変換関数 @@ -1423,19 +1427,19 @@ EMQXはSparkplug Bメッセージのデコード・エンコード用の特殊 `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 | -| `%6N` | マイクロ秒（ナノ秒の最初の6桁） | 000000 - 999999 | -| `%3N` | ミリ秒（ナノ秒の最初の3桁） | 000 - 999 | -| `%z` | タイムゾーンオフセット（±hhmm形式） | -1159 - +1159 | -| `%:z` | タイムゾーンオフセット（±hh:mm形式） | -11:59 - +11:59 | -| `%::z` | タイムゾーンオフセット（±hh:mm:ss形式） | -11:59:59 - +11:59:59 | +| `%6N` | マイクロ秒（ナノ秒の先頭6桁） | 000000 - 999999 | +| `%3N` | ミリ秒（ナノ秒の先頭3桁） | 000 - 999 | +| `%z` | タイムゾーンオフセット（±hhmm） | -1159 - +1159 | +| `%:z` | タイムゾーンオフセット（±hh:mm） | -11:59 - +11:59 | +| `%::z` | タイムゾーンオフセット（±hh:mm:ss） | -11:59:59 - +11:59:59 | 例： @@ -1445,13 +1449,13 @@ 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からの正負の時間オフセット -- `local`：システムのローカルタイムゾーンに対応するオフセット +- `±hh[:mm][:ss]` または `±hh[mm][ss]`：UTCからの正負の時刻オフセット +- `local`：システムのローカルタイムゾーンのオフセット 例： @@ -1465,7 +1469,7 @@ date_to_unix_ts('second', 14400, '%Y-%m-%d %H:%M:%S%:z', '2024-02-23 15:00:00') Unix時間 `Time` を指定フォーマットの日時文字列に変換します。`Unit` はUnix時間の単位、`Offset` は出力日時のタイムゾーンオフセット、`FormatString` は出力フォーマットを表します。 -`date_to_unix_ts/3, 4` を参照し、`Unit`, `Offset`, `FormatString` の値を指定してください。 +`date_to_unix_ts/3,4` と同様の値を指定可能です。 例： @@ -1479,7 +1483,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 +1491,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' @@ -1495,7 +1499,7 @@ now_rfc3339('microsecond') = '2024-02-23T10:26:38.009706+08:00' ### now_timestamp() -> integer -現在のシステム時刻を秒単位のUnixタイムスタンプで返します。例： +現在時刻を秒単位のUnixタイムスタンプで返します。例： ```bash now_timestamp() = 1708913853 @@ -1503,7 +1507,7 @@ now_timestamp() = 1708913853 ### now_timestamp(Unit: string) -> integer -`now_timestamp/0` と同様ですが、`Unit` で時間単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポートします。例： +`now_timestamp/0` と同様ですが、`Unit` で時間単位を指定できます。例： ```bash now_timestamp('microsecond') = 1708913828814315 @@ -1520,7 +1524,7 @@ rfc3339_to_unix_ts('2024-02-23T15:56:30+08:00') = 1708674990 ### rfc3339_to_unix_ts(DateTimeString: string, Unit: string) -> integer -`rfc3339_to_unix_ts/1` と同様ですが、`Unit` で返すUnixタイムスタンプの単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポートします。例： +`rfc3339_to_unix_ts/1` と同様ですが、返却するUnixタイムスタンプの単位を `Unit` で指定できます。例： ```bash rfc3339_to_unix_ts('2024-02-23T15:56:30.87Z', 'second') = 1708703790 @@ -1531,11 +1535,11 @@ rfc3339_to_unix_ts('2024-02-23T15:56:30.535904509Z', 'nanosecond') = 17087037905 ### timezone_to_offset_seconds(Offset: string) -> integer -タイムゾーンオフセット文字列を秒数の整数に変換します。以下の形式をサポートします： +タイムゾーンオフセット文字列を秒数の整数に変換します。サポートされる形式： - `Z` または `z`：UTCオフセット00:00 -- `±hh[:mm][:ss]` または `±hh[mm][ss]`：UTCからの正負の時間オフセット -- `local`：システムのローカルタイムゾーンに対応するオフセット +- `±hh[:mm][:ss]` または `±hh[mm][ss]`：UTCからの正負の時刻オフセット +- `local`：システムのローカルタイムゾーンのオフセット 例： @@ -1547,7 +1551,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 +1559,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` で時間単位を指定できます。例： ```bash unix_ts_to_rfc3339(1708671600766, 'millisecond') = '2024-02-23T15:00:00.766+08:00' @@ -1565,7 +1569,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 +1579,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 +1589,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 +1628,20 @@ uuid_v4_no_hyphen() = 'd7a39aa4195a42068b962eb9a665503e' 環境変数 `Name` の値を返します。以下の制約があります： -- OS環境変数を読み取る際、`EMQXVAR_` プレフィックスが付加されます。例えば、`getenv('FOO_BAR')` は `EMQXVAR_FOO_BAR` を読み取ります。 -- OS環境変数から読み込んだ値は不変です。 +- 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を返します。SQL式の `CASE WHEN is_null(payload.value) THEN 0 ELSE payload.value END` と同等ですが簡潔です。 ::: tip 注意 -EMQXルールSQLでは、null値の文字列表現はデフォルトで `'undefined'` です。 +EMQXルールSQLではnull値の文字列表現はデフォルトで `'undefined'` です。 ::: @@ -1647,6 +1651,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..2d645582a 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 データ保存に適しています。 +- **メッセージ変換**：EMQXのルール内でメッセージに対して高度な処理や変換を行い、その後Snowflakeに書き込むことで、後続の保存や利用を容易にします。 +- **柔軟なデータ操作**：Snowflake Sinkは、Snowflakeに書き込む特定のフィールドを選択可能であり、ビジネスニーズに応じた効率的かつ動的なストレージ構成を実現します。 +- **統合されたビジネスプロセス**：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 Data Sources] +snowflake = SnowflakeDSIIDriver +``` -このスクリプトはテスト用であり、本番環境での ODBC ドライバー設定方法の推奨ではありません。公式の [Linux 向けインストール手順](https://docs.snowflake.com/en/developer-guide/odbc/odbc-linux) を参照してください。 +`/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.ini`ファイルを作成または更新し、ODBC接続を設定： ``` 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://` | +| 項目 | 値 | +| ------------------------ | ------------------------------------------------ | +| Data Source Name (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鍵ペアの生成が完了したら、Snowflakeのデータベース、テーブル、ステージ、パイプをSQLコマンドで作成します。 -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,61 @@ ODBC ドライバーのセットアップと RSA キーペア生成後、Snowfla ## コネクターの作成 -Snowflake Sink を追加する前に、EMQX で Snowflake への接続を確立するためのコネクターを作成します。 +Snowflake Sinkを追加する前に、EMQXでSnowflakeとの接続を確立するためのコネクターを作成します。 1. ダッシュボードの **Integration** -> **Connector** ページに移動します。 + 2. 右上の **Create** ボタンをクリックします。 + 3. コネクタータイプとして **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のユーザー名/パスワード認証でSnowflakeに接続するためのパスワードです。任意入力です。 + - ここにパスワード（例：`Snowpipeuser99`）を入力するか、 + - `/etc/odbc.ini`に設定するか、 + - キーペア認証を使用する場合は空欄のままにします。 + + ::: tip + + 認証にはPasswordかPrivate Keyのいずれかを使用してください。両方設定しないでください。どちらも設定しない場合は、適切な認証情報が`/etc/odbc.ini`に設定されていることを確認してください。 + + ::: + + - **Proxy**：HTTPプロキシ経由でSnowflakeに接続する場合の設定です。HTTPSプロキシはサポートされていません。デフォルトはプロキシなしです。プロキシを有効にする場合は`Enable Proxy`を選択し、以下を入力します。 + - **Proxy Host**：プロキシサーバーのホスト名またはIPアドレス + - **Proxy Port**：プロキシサーバーのポート番号 + - **Private Key Path**：SnowflakeへのODBC接続認証に使用する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](#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に書き込むルールの作成方法を示します。 1. ダッシュボードの **Integration** -> **Rules** ページに移動します。 2. 右上の **Create** ボタンをクリックします。 -3. ルールID に `my_rule` と入力し、SQL エディターに以下のルール SQL を入力します： +3. ルールIDに `my_rule` を入力し、SQLエディターに以下のルールSQLを入力します。 ```sql SELECT @@ -239,97 +319,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秘密鍵ファイルの内容を入力します。安全な認証に使用し、パイプへのアクセスに必要です。ファイルパスを使用する場合はクラスター内すべてのノードで同一かつ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](#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` にメッセージをパブリッシュします： +MQTTクライアントMQTTXを使い、トピック`t/1`にメッセージをパブリッシュします。 ```bash mqttx pub -i emqx_c -t t/1 -m '{ "msg": "Hello Snowflake" }' ``` -この操作を数回繰り返して複数のテストメッセージを生成してください。 +複数回繰り返して複数のテストメッセージを生成してください。 -### Snowflake 内のデータ確認 +### Snowflake内のデータ確認 -テストメッセージ送信後、Snowflake にデータが正常に書き込まれたかを確認します。 +テストメッセージ送信後、Snowflakeにデータが正常に書き込まれたかを確認します。 -1. Snowflake のウェブインターフェースを開き、認証情報で Snowflake コンソールにログインします。 +1. SnowflakeのWebインターフェースにログインします。 -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`などのフィールドを含むすべてのレコードが表示されます。 -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** | 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..2dd13dba9 100644 --- a/ja_JP/last_translation_commit +++ b/ja_JP/last_translation_commit @@ -1 +1 @@ -c55404f5618e14f7e22283490c620bc71fe5cb6c +e90a4a802ec0ece4850a05d8c5e5cc12a3ee8883 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..64c652e5a 100644 --- a/ja_JP/observability/opentelemetry/e2e-traces.md +++ b/ja_JP/observability/opentelemetry/e2e-traces.md @@ -1,100 +1,122 @@ # OpenTelemetryベースのエンドツーエンドMQTTトレーシング -現代の分散システムにおいて、リクエストの流れを追跡しパフォーマンスを分析することは、信頼性と可観測性を確保するために不可欠です。エンドツーエンドトレーシングは、リクエストの開始から終了までの全経路をキャプチャすることを目的とした概念であり、システムの挙動やパフォーマンスに関する深い洞察を得ることができます。 +現代の分散システムにおいて、リクエストの流れを追跡し、パフォーマンスを分析することは、信頼性と可観測性を確保するために不可欠です。エンドツーエンドトレーシングは、リクエストの開始から終了までの全経路をキャプチャすることを目的とした概念であり、システムの挙動やパフォーマンスに関する深い洞察を得ることが可能です。 -EMQXはバージョン5.8.3以降、MQTTプロトコルに特化したOpenTelemetryベースのエンドツーエンドトレーシング機能を統合しています。この機能により、特にマルチノードクラスター環境において、メッセージのパブリッシュ、ルーティング、配信を明確にトレースできます。これにより、システムパフォーマンスの最適化だけでなく、迅速な障害箇所の特定やシステム信頼性の向上にも役立ちます。 +EMQXはバージョン5.8.3以降、MQTTプロトコルに特化したOpenTelemetryベースのエンドツーエンドトレーシング機能を統合しています。この機能により、特にマルチノードのクラスター環境において、メッセージのパブリッシュ、ルーティング、配信を明確にトレースできます。これにより、システムパフォーマンスの最適化だけでなく、迅速な障害箇所の特定やシステムの信頼性向上にも寄与します。 -本ページでは、MQTTメッセージのフローを包括的に可視化するために、EMQXでエンドツーエンドトレーシング機能を有効化する方法を詳しく解説します。 +本ページでは、EMQXでエンドツーエンドトレーシング機能を有効化し、MQTTメッセージフローの包括的な可視化を実現するための詳細な手順を解説します。 -## OpenTelemetry Collectorのセットアップ +## OpenTelemetryコレクターのセットアップ -設定の詳細については、[OpenTelemetry Collectorのセットアップ](./traces.md#setting-up-opentelemetry-collector)を参照してください。 +設定の詳細については、[OpenTelemetryコレクターのセットアップ](./traces.md#setting-up-opentelemetry-collector)を参照してください。 ## 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` を選択します。 -5. **Save Changes** をクリックして設定を保存します。 + - **Endpoint**：トレースデータのエクスポート先アドレスを設定します。デフォルトは `http://localhost:4317` です。 -OpenTelemetryエンドツーエンドトレーシング ダッシュボード設定画面 + - **Headers**：トレースエクスポートリクエストにカスタムHTTPヘッダーを追加します。OpenTelemetryコレクターが認証やAPIキー、トークンなどのカスタムヘッダーを必要とする場合に使用します。各ヘッダーはキーと値のペアで指定してください。 + + OpenTelemetryコレクターがBasic認証を使用する場合は、`authorization` ヘッダーを以下の形式で追加する必要があります： + + ``` + Key: authorization + Value: Basic dXNlcjpwYXNzd29yZA== + ``` + + この設定により、HTTPベースの認証を要求するコレクターとの互換性が向上します。 + + - **Enable TLS**：必要に応じてTLS暗号化を有効にします。通常は本番環境のセキュリティ要件に応じて設定します。 + + - **Trace Mode**：`End-to-End` を選択し、エンドツーエンドトレーシング機能を有効化します。 + + - **Cluster Identifier**：スパン属性に付加するプロパティ値を設定し、どの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** をクリックして設定を保存します。 + +Otel-E2E-Trace-dashboard-page ### 設定ファイルからエンドツーエンドトレーシングを設定する -EMQXがローカルで稼働している前提で、`cluster.hocon` ファイルに以下の設定を追加します。 +EMQXがローカルで稼働している場合、`cluster.hocon` ファイルに以下の設定を追加してください。 -設定オプションの詳細は、[EMQXダッシュボード監視統合のOpenTelemetry項目](http://localhost:18083/#/monitoring/integration)を参照してください。 +設定オプションの詳細は、[EMQXダッシュボード監視統合](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をクライアントとして使用し、異なるノードで同じトピックをサブスクライブします。 @@ -112,7 +134,7 @@ opentelemetry { 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数は異なります。 + トレースをクリックすると、詳細なスパン情報とトレースタイムラインが表示されます。サブスクライバー数、ノード間のメッセージルーティング、QoSレベル、`msg_trace_level` の設定に応じて、MQTTメッセージトレースに含まれるスパン数は異なります。 - 以下は、2クライアントがQoS 2でサブスクライブし、パブリッシャーがQoS 2のメッセージを送信、`msg_trace_level` が2に設定されている場合のトレースタイムラインとspan情報の例です。 + 以下は、2人のクライアントがQoS 2でサブスクライブし、パブリッシャーがQoS 2のメッセージを送信し、`msg_trace_level` が2に設定されている場合の例です。 - 特に、クライアント `mqttx_9137a6bb` がパブリッシャーとは異なるEMQXノードに接続しているため、ノード間の送信を表す2つの追加span（`message.forward` と `message.handle_forward`）が表示されています。 + 特に、クライアント `mqttx_9137a6bb` はパブリッシャーとは異なるEMQXノードに接続しているため、ノード間の送信を表す2つの追加スパン（`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のオーバーロード管理 +## トレーススパンの過負荷管理 -EMQXはトレースspanを蓄積し、定期的にバッチでエクスポートします。エクスポート間隔は `opentelemetry.trace.scheduled_delay` パラメータで制御され、デフォルトは5秒です。バッチトレースspanプロセッサにはオーバーロード保護機能があり、最大蓄積数（デフォルト2048span）を超えると新規spanは破棄されます。以下の設定でこの制限を調整可能です。 +EMQXはトレーススパンを蓄積し、定期的にバッチでエクスポートします。エクスポート間隔は `opentelemetry.trace.scheduled_delay` パラメータで制御され、デフォルトは5秒です。バッチトレーススパンプロセッサには過負荷保護機能があり、スパンの蓄積は上限まで許容されます。デフォルトの上限は2048スパンです。以下の設定でこの上限を調整できます： ```yaml opentelemetry { @@ -162,14 +184,14 @@ opentelemetry { } ``` -`max_queue_size` の上限に達すると、現在のキューがエクスポートされるまで新規トレースspanは破棄されます。 +`max_queue_size` の上限に達すると、新規のトレーススパンは現在のキューがエクスポートされるまで破棄されます。 ::: tip 補足 -トレース対象メッセージが多数のサブスクライバーに配信される場合や、メッセージ量が多くサンプリング率が高い場合、オーバーロード保護により多くのspanが破棄され、エクスポートされるspanはごく一部になる可能性があります。 +トレース対象のメッセージが多数のサブスクライバーに配信される場合や、メッセージ量が多くサンプリング率が高い場合、過負荷保護により多くのスパンが破棄され、エクスポートされるスパンはごく一部になる可能性があります。 -エンドツーエンドトレーシングモードでは、メッセージ量やサンプリング率に応じて `max_queue_size` を増やし、`scheduled_delay` を短縮してspanのエクスポート頻度を上げることを検討してください。これによりオーバーロード保護によるspanの損失を抑制できます。 +エンドツーエンドトレーシングモードでは、メッセージ量やサンプリング率に応じて `max_queue_size` を増加させ、`scheduled_delay` を短縮してスパンのエクスポート頻度を上げることを検討してください。これにより過負荷保護によるスパンの損失を防げます。 -**ただし、エクスポート頻度の増加やキューサイズの拡大はシステムリソース消費を増加させるため、メッセージTPSや利用可能なシステムリソースを十分に見積もった上で適切に設定してください。** +**ただし、エクスポート頻度の増加やキューサイズの拡大はシステムリソースの消費増加を招きます。メッセージTPSや利用可能なシステムリソースを十分に見積もった上で、本機能を有効化し、適切な設定を適用してください。** ::: diff --git a/ja_JP/observability/opentelemetry/logs.md b/ja_JP/observability/opentelemetry/logs.md index c38f0624c..d57c8e0a2 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`にリダイレクトするためのdebugエクスポーターの設定手順を説明します。 1. `otel-logs-collector-config.yaml`という名前でOpenTelemetry Collectorの設定ファイルを作成します。 @@ -48,8 +49,8 @@ EMQXのOpenTelemetryログを有効にする前に、OpenTelemetry Collectorお volumes: - ./otel-logs-collector-config.yaml:/etc/otel-collector-config.yaml ports: - - "13133:13133" # ヘルスチェック拡張 - - "4317:4317" # OTLP gRPCレシーバー + - "13133:13133" # Health check extension + - "4317:4317" # OTLP gRPC receiver ``` 3. Docker Composeを使ってCollectorを起動します。 @@ -61,40 +62,43 @@ EMQXのOpenTelemetryログを有効にする前に、OpenTelemetry Collectorお 4. 起動後、OpenTelemetry Collectorは[http://localhost:4317](http://localhost:4317/)でアクセス可能になります。 -## EMQXでOpenTelemetryログハンドラーを有効化 +## 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 + Otel-logs-HTTP-ブリッジの例 -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 { @@ -102,11 +106,10 @@ opentelemetry { } ``` -`max_queue_size`の上限に達すると、新しいログイベントは現在のキューがエクスポートされるまで破棄されます。 +`max_queue_size`の上限に達すると、現在のキューがエクスポートされるまで新しいログイベントは破棄されます。 -::: tip 補足 +::: tip 注意事項 -OpenTelemetryログの過負荷保護は、デフォルトの[EMQXログハンドラー](../log.md)の過負荷保護とは独立して動作します。 -そのため、設定によっては同じログイベントがOpenTelemetryハンドラーで破棄される一方、EMQXのデフォルトログハンドラーでは記録される場合や、その逆もあり得ます。 +OpenTelemetryログの過負荷保護は、デフォルトの[EMQXログハンドラー](../log.md)の過負荷保護とは独立して動作します。そのため、設定によっては同じログイベントがOpenTelemetryハンドラーで破棄されつつ、デフォルトのEMQXログハンドラーでは記録される場合や、その逆もあり得ます。 ::: diff --git a/ja_JP/observability/opentelemetry/metrics.md b/ja_JP/observability/opentelemetry/metrics.md index 233044f34..e15f9cf2a 100644 --- a/ja_JP/observability/opentelemetry/metrics.md +++ b/ja_JP/observability/opentelemetry/metrics.md @@ -1,14 +1,14 @@ # 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との統合を行う前に、OpenTelemetryおよびPrometheusをデプロイし、設定しておく必要があります。 - [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/getting-started)をデプロイします。 -- CollectorのgRPC受信ポート（デフォルトは4317）とPrometheusメトリクスエクスポートポート（8889）を設定します。 +- CollectorのgRPC受信ポート（デフォルト4317）およびPrometheusメトリクスエクスポートポート（8889）を設定します。 ```yaml # otel-collector-config.yaml @@ -47,13 +47,18 @@ scrape_configs: ## EMQXでOpenTelemetryメトリクスを有効化する -EMQXのOpenTelemetryメトリクス機能との統合は、EMQXダッシュボードまたは設定ファイルで行えます。ダッシュボードでは、左側のナビゲーションメニューから **Management** -> **Monitoring** をクリックし、**Integration** タブでメトリクスの設定を行います。 +EMQXのOpenTelemetryメトリクス機能との統合は、EMQX Dashboardまたは設定ファイルで行えます。Dashboardでは、左のナビゲーションメニューから **Management** -> **Monitoring** をクリックし、**Integration** タブでメトリクスの設定を行います。 EMQXがローカルで動作している場合、以下の設定をEMQXの `cluster.hocon` ファイルに追加してください。 ```bash opentelemetry { - exporter { endpoint = "http://localhost:4317" } + exporter { + endpoint = "http://localhost:4317" + headers { + authorization = "Basic dXNlcjpwYXNzd29yZA==" + } + } metrics { interval = "10s" } diff --git a/ja_JP/observability/opentelemetry/opentelemetry.md b/ja_JP/observability/opentelemetry/opentelemetry.md index e3c32ffb7..604fa682d 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..2b34a1102 100644 --- a/ja_JP/support/technical-support.md +++ b/ja_JP/support/technical-support.md @@ -1,17 +1,17 @@ --- 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以上のオフィスを展開しています。 +EMQのグローバルR&Dセンターはストックホルムに位置し、アメリカ大陸、ヨーロッパ、アジア太平洋地域に10以上のオフィスを展開しています。 -EMQX製品や当社のIoTソリューションについてご質問がある場合は、以下までお気軽にお問い合わせください。 +EMQX製品や当社のIoTソリューションに関するご質問がございましたら、以下までお気軽にお問い合わせください。 **EMQ** @@ -27,7 +27,7 @@ EMQX製品や当社のIoTソリューションについてご質問がある場 **所在地:** -- 本社：中国 浙江省 杭州市 餘杭区 龍源路88号 3号館 A301 +- 本社：中国 浙江省 杭州市 餘杭区 龍源路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 @@ -35,13 +35,13 @@ EMQX製品や当社のIoTソリューションについてご質問がある場 EMQXサービスチームは、専門的なサポートを提供いたします。 - IoTソリューションの設計、デプロイメント、カスタマイズに関する専門的なサポートは、[EMQXサービスチーム](https://www.emqx.com/en/contact?product=emqx)までご連絡ください。 -- 提供している商用サポート内容については、[EMQXサポートポータル](https://www.emqx.com/en/support)をご覧ください。 +- [EMQXサポートポータル](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でも情報発信を行っています。 +また、以下の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)