diff --git a/docusaurus/docs/getting-started/code-examples/canister-logs/img/canister-logs.jpg b/docusaurus/docs/getting-started/code-examples/canister-logs/img/canister-logs.jpg new file mode 100644 index 0000000..4d85ff7 Binary files /dev/null and b/docusaurus/docs/getting-started/code-examples/canister-logs/img/canister-logs.jpg differ diff --git a/docusaurus/docs/getting-started/code-examples/canister-logs/index.md b/docusaurus/docs/getting-started/code-examples/canister-logs/index.md new file mode 100644 index 0000000..6e47328 --- /dev/null +++ b/docusaurus/docs/getting-started/code-examples/canister-logs/index.md @@ -0,0 +1,148 @@ +--- +title: 容器日志 +image: './img/canister-logs.jpg' +description: 如何使用互联网计算机 (IC) 的容器日志 +keywords: [DFINITY, ICP, IC, 互联网计算机, canister, logs, 容器，日志] +--- + +import TeamContact from '../../../contact.md'; + +# 容器日志 + +![容器日志](./img/canister-logs.jpg) + +## 概览 {#overview} + +本教程演示了如何使用互联网计算机 (IC) 的[容器](https://ic123.xyz/docs/getting-started/ic-glossary/#canister)日志功能。 + +容器日志功能旨在为开发人员提供途径以查看容器行为，并在容器执行发生错误时提供帮助。该功能支持以下日志信息： + +- Heartbeats +- 计时器（Timers） +- `Pre/post` 更新脚本 和 `canister_init` 方法 +- 更新调用 +- 查询调用（仅支持在 replicated 模式下执行的查询调用） + +即使在执行过程中发生错误，容器的[控制者](https://ic123.xyz/docs/getting-started/ic-glossary/#controller)仍然能够使用 `dfx canister logs` 命令检索容器日志。 + +## 要求 {#prerequisites} + +- 下载并安装 [IC SDK](https://ic123.xyz/docs/getting-started/install-dfx/)。 + +## 创建工程 {#create-project} + +进入您的工程目录，执行一下命令创建新的 dfx 工程。 + +```bash +dfx new canister_logs +``` + +在接下来的步骤中： + +- 选择 `Rust` 作为后端语言； +- 选择 `No frontend canister`。 + +从而完成工程创建。 + +## 更新工程 {#update-project} + +这里我们需要将默认代码更新，从而使用容器日志功能。 + +### 更新 Rust 代码 + +请打开 `canister_logs` 工程目录下的 `src/canister_logs_backend/src/lib.rs` 文件，并将其代码替换为如下文本： + +```rust +use std::cell::RefCell; + +use ic_cdk::{ + export_candid, println, +}; + +thread_local! { + // create a cell that holds a counter + static COUNTER: std::cell::RefCell = RefCell::default(); +} + +#[ic_cdk::update] +fn produce_logs() { + // print the counter value + COUNTER.with_borrow_mut(|counter| { + println!("counter: {}", *counter); + *counter += 1; + }); +} + +export_candid!(); +``` + +该代码定义了一个计数器 `COUNTER`，并通过 `produce_logs` 方法更新计数器、并输出日志。 + +### 更新 Candid 文件 + +由于我们更新了容器接口，我们需要更新对应的 `candid` 文件。请参照[该文档](https://internetcomputer.org/docs/current/developer-docs/backend/rust/generating-candid) 进行更新。 + +基本步骤如下： + +- 执行如下脚本安装 `candid-extractor` 工具。 + ```bash + cargo install candid-extractor` + ``` +- 执行如下脚本编译容器。 + ```bash + cargo build --release --target wasm32-unknown-unknown --package canister_logs_backend + ``` +- 执行如下脚本导出新的 candid 文件。 + ```bash + candid-extractor target/wasm32-unknown-unknown/release/canister_logs_backend.wasm > canister_logs_backend.did + ``` +- 替换 `src/canister_logs_backend/canister_logs_backend.did` 文件。 + +## 本地部署 {#deploy} + +完成代码更新后，您可以执行以下脚本将您的容器部署到 IC 的本地开发环境。 + +```bash +dfx start --background +dfx deploy +``` + +如果成功，您将会看到类似如下的输出信息： + +```bash +... +Deployed canisters. +URLs: + Backend canister via Candid interface: + canister_logs_backend: http://127.0.0.1:4943/?canisterId=a3shf-5eaaa-aaaaa-qaafa-cai&id=asrmz-lmaaa-aaaaa-qaaeq-cai +... +``` + +## 测试 {#test} + +您可以调用 `canister_logs_backend` 容器的 `produce_logs` 方法来递增计数器，并获得以下命令行输出： + +```bash +dfx canister call canister_logs_backend produce_logs +2024-06-04 21:14:25.882276 UTC: [Canister asrmz-lmaaa-aaaaa-qaaeq-cai] counter: 0 +() +dfx canister call canister_logs_backend produce_logs +2024-06-04 21:18:18.094003 UTC: [Canister asrmz-lmaaa-aaaaa-qaaeq-cai] counter: 1 +() +dfx canister call canister_logs_backend produce_logs +2024-06-04 21:18:46.036022 UTC: [Canister asrmz-lmaaa-aaaaa-qaaeq-cai] counter: 2 +() +``` + +然后您可以通过 `dfx canister logs` 查看容器日志： + +```bash +dfx canister logs canister_logs_backend +[0. 2024-06-04T21:14:25.882276Z]: counter: 0 +[1. 2024-06-04T21:18:18.094003Z]: counter: 1 +[2. 2024-06-04T21:18:46.036022Z]: counter: 2 +``` + +以上教程展示了 Rust 中最基本的容器日志用法。您也可以参考 DFINITY 基金会的官方示例、分别查看 [Rust](https://github.com/dfinity/examples/tree/master/rust/canister_logs) 和 [Motoko](https://github.com/dfinity/examples/tree/master/motoko/canister_logs) 版本。 + + diff --git a/docusaurus/docs/getting-started/code-examples/index.md b/docusaurus/docs/getting-started/code-examples/index.md index 1f5838b..adbd3df 100644 --- a/docusaurus/docs/getting-started/code-examples/index.md +++ b/docusaurus/docs/getting-started/code-examples/index.md @@ -35,6 +35,10 @@ IC 提供了很多范例供开发者参考。以下所有的示例都开源， ## 可认证变量 {#certified-variables} -[可认证变量](./certified-variables/index.md) 示例介绍了如何使用互联网计算机 (IC) 的可认证变量功能。 +[可认证变量](./certified-variables/index.md)示例介绍了如何使用互联网计算机 (IC) 的可认证变量功能。 + +## 容器日志 {#canister-logs} + +[容器日志](./canister-logs/index.md)示例演示了如何使用互联网计算机 (IC) 的容器日志功能。 ## To be continued diff --git a/docusaurus/docs/getting-started/use-dfx/index.md b/docusaurus/docs/getting-started/use-dfx/index.md index a9634a4..af05b2f 100644 --- a/docusaurus/docs/getting-started/use-dfx/index.md +++ b/docusaurus/docs/getting-started/use-dfx/index.md @@ -621,6 +621,27 @@ Controllers: r7inp-6aaaa-aaaaa-aaabq-cai Module hash: 0x3eadce8399b6bc9450bfb8bb54adefc1e27b2564146684d4c6d41a62c4110b73 ``` +### 查看容器日志 {#canister-logs} + +`dfx canister logs` 命令可以显示容器的日志。它的基本用法如下： + +``` +dfx canister logs +``` + +下面是一个示例，显示来自 `hello_world` 容器的日志。 + +``` +dfx canister logs hello_world +``` + +该命令将显示类似于以下内容的输出： + +``` +[0. 2024-06-04T21:14:25.882276Z]: Some text message +[1. 2024-06-04T21:18:18.094003Z]: (bytes) 0xc0ffee +``` + ### 安装容器代码 {#canister-install} `dfx canister install` 命令可以用来安装容器代码。它的基本用法如下： diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js index 6b9cec5..39e0338 100644 --- a/docusaurus/sidebars.js +++ b/docusaurus/sidebars.js @@ -39,6 +39,7 @@ const sidebars = { "getting-started/code-examples/https-outcalls/index", "getting-started/code-examples/certified-variables/index", "getting-started/code-examples/dfx-dependencies/index", + "getting-started/code-examples/canister-logs/index", ] }, ],