Skip to content

Commit

Permalink
Update docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
yang-xiaodong committed Mar 14, 2024
1 parent ed4a841 commit 5844985
Show file tree
Hide file tree
Showing 13 changed files with 35 additions and 20 deletions.
9 changes: 8 additions & 1 deletion docs/content/user-guide/en/cap/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,4 +152,11 @@ By default, CAP will only read one message from the message queue, then execute
If set to true, the consumer will prefetch some messages to the memory queue, and then distribute them to the .NET thread pool for execution.

!!! note "Precautions"
Setting it to true may cause some problems. When the subscription method executes too slowly and takes too long, it will cause the retry thread to pick up messages that have not yet been executed. The retry thread picks up messages from 4 minutes (FallbackWindowLookbackSeconds) ago by default , that is to say, if the message backlog of more than 4 minutes (FallbackWindowLookbackSeconds) on the consumer side will be picked up again and executed again
Setting it to true may cause some problems. When the subscription method executes too slowly and takes too long, it will cause the retry thread to pick up messages that have not yet been executed. The retry thread picks up messages from 4 minutes (FallbackWindowLookbackSeconds) ago by default , that is to say, if the message backlog of more than 4 minutes (FallbackWindowLookbackSeconds) on the consumer side will be picked up again and executed again

#### EnablePublishParallelSend

> Default: false, The (7.2 <= Version < 8.1) the default behavior is true
By default, messages sent are first placed into the Channel in memory and then processed linearly.
If set to true, the task of sending messages will be processed in parallel by the .NET thread pool, which will greatly increase the speed of sending.
6 changes: 3 additions & 3 deletions docs/content/user-guide/en/cap/messaging.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ Retrying plays an important role in the overall CAP architecture design, CAP ret

During the message sending process, when the broker crashes or the connection fails or an abnormality occurs, CAP will retry the sending. Retry 3 times for the first time, retry every minute after 4 minutes (FallbackWindowLookbackSeconds), and +1 retry. When the total number of retries reaches 50, CAP will stop retrying.

You can adjust the total number of retries by setting [FailedRetryCount](../configuration#failedretrycount) in CapOptions Or use [FailedThresholdCallback](../configuration#failedthresholdcallback) to receive notifications when the maximum retry count is reached.
You can adjust the total number of retries by setting [FailedRetryCount](configuration.md#failedretrycount) in CapOptions Or use [FailedThresholdCallback](configuration.md#failedthresholdcallback) to receive notifications when the maximum retry count is reached.

It will stop when the maximum number of times is reached. You can see the reason for the failure in Dashboard and choose whether to manually retry.

Expand All @@ -141,10 +141,10 @@ Whether sending fails or consumption fails, we will store the exception message

There is an `ExpiresAt` field in the database message table indicating the expiration time of the message. When the message is sent successfully, status will be changed to `Successed`, and `ExpiresAt` will be set to **1 day** later.

Consuming failure will change the message status to `Failed` and `ExpiresAt` will be set to **15 days** later (You can use [FailedMessageExpiredAfter](../configuration#failedmessageexpiredafter) configuration items to custom).
Consuming failure will change the message status to `Failed` and `ExpiresAt` will be set to **15 days** later (You can use [FailedMessageExpiredAfter](configuration.md#failedmessageexpiredafter) configuration items to custom).

By default, the data of the message in the table is deleted every **5 minutes** to avoid performance degradation caused by too much data. The cleanup strategy `ExpiresAt` is performed when field is not empty and is less than the current time.

That is to say, the message with the status Failed (by default they have been retried 50 times), if you do not have manual intervention for 15 days, it will **also be** cleaned up.

You can use [CollectorCleaningInterval](../configuration#collectorcleaninginterval) configuration items to custom the interval time.
You can use [CollectorCleaningInterval](configuration.md#collectorcleaninginterval) configuration items to custom the interval time.
4 changes: 2 additions & 2 deletions docs/content/user-guide/en/monitoring/diagnostics.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,13 +71,13 @@ dotnet-counters monitor --process-id=25496 --counters=DotNetCore.CAP.EventCounte

process-id: The ID of the CAP process to collect counter data from.

![img](/img/dotnet-counters.gif)
![img](../../../img/dotnet-counters.gif)

### Monitor with dashboard

You can configure `x.UseDashboard()` to open the dashboard to view Metrics graph charts.

![img](/img/dashboard-metrics.gif)
![img](../../../img/dashboard-metrics.gif)

In the Realtime Metric Graph, the time axis will scroll in real time over time so that you can see the rate of publishing and consuming messages per second, And the consumer execution time is "dotted" on the Y1 axis (Y0 axis is the rates, and the Y1 axis is the execution elpsed time).

Expand Down
4 changes: 2 additions & 2 deletions docs/content/user-guide/en/transport/aws-sqs.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,15 +32,15 @@ public void TestBar(DateTime value)
```
After CAP startups, you will see in SNS management console:

![img](/img/aws-sns-demo.png)
![img](../../../img/aws-sns-demo.png)

### SQS

For each consumer group, CAP will create a corresponding SQS queue, the name of the queue is the name of the `DefaultGroup` in the configuration options, and the queue type is Standard.

The SQS queue will subscribe to Topic in SNS, as shown below:

![img](/img/aws-sns-demo.png)
![img](../../../img/aws-sns-demo.png)

!!! warning "Precautions"
Due to the limitation of AWS SNS, when you remove the subscription method, CAP will not delete topics or queues on AWS SNS or SQS, you need to delete them manually.
Expand Down
2 changes: 1 addition & 1 deletion docs/content/user-guide/en/transport/kafka.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ CustomHeaders | Custom subscribe headers | Func<> | N/A

When the message sent from a heterogeneous system, because of the CAP needs to define additional headers, so an exception will occur at this time. By providing this parameter to set the custom headersn to make the subscriber works.

You can find the description of heterogeneous system integration [here](../../cap/messaging#heterogeneous-system-integration).
You can find the description of heterogeneous system integration [here](../cap/messaging.md#heterogeneous-system-integration).

Sometimes, if you want to get additional context information from Broker, you can also add it through this option. For example, add information such as Offset or Partition.

Expand Down
2 changes: 1 addition & 1 deletion docs/content/user-guide/en/transport/rabbitmq.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ services.AddCap(x =>

When the message sent from the RabbitMQ management console or a heterogeneous system, because of the CAP needs to define additional headers, so an exception will occur at this time. By providing this parameter to set the custom headersn to make the subscriber works.

You can find the description of [Header Information](../cap/messaging#heterogeneous-system-integration) here.
You can find the description of [Header Information](../cap/messaging.md#heterogeneous-system-integration) here.

Example:

Expand Down
9 changes: 8 additions & 1 deletion docs/content/user-guide/zh/cap/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,4 +156,11 @@ services.AddCap(config =>
如果设置为 true, 消费端会将消息预取到内存队列,然后再放入.NET 线程池并行执行。

!!! note "注意事项"
设置为 true 可能会产生一些问题,当订阅方法执行过慢耗时太久时,会导致重试线程拾取到还未执行的的消息。重试线程默认拾取4分钟前(FallbackWindowLookbackSeconds 配置项)的消息,也就是说如果消费端积压了超过4分钟(FallbackWindowLookbackSeconds 配置项)的消息就会被重新拾取到再次执行
设置为 true 可能会产生一些问题,当订阅方法执行过慢耗时太久时,会导致重试线程拾取到还未执行的的消息。重试线程默认拾取4分钟前(FallbackWindowLookbackSeconds 配置项)的消息,也就是说如果消费端积压了超过4分钟(FallbackWindowLookbackSeconds 配置项)的消息就会被重新拾取到再次执行

#### EnablePublishParallelSend

> 默认值: false
默认情况下,发送的消息都先放置到内存同一个Channel中,然后线性处理。
如果设置为 true,则发送消息的任务将由.NET线程池并行处理,这会大大提高发送的速度。
6 changes: 3 additions & 3 deletions docs/content/user-guide/zh/cap/messaging.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ CAP 接收到消息之后会将消息进行 Persistent(持久化), 有关

在消息发送过程中,当出现 Broker 宕机或者连接失败的情况亦或者出现异常的情况下,这个时候 CAP 会对发送的重试,第一次重试次数为 3,4分钟后以后每分钟重试一次,进行次数 +1,当总次数达到50次后,CAP将不对其进行重试。

你可以在 CapOptions 中设置 [FailedRetryCount](../configuration#failedretrycount) 来调整默认重试的总次数,或使用 [FailedThresholdCallback](../configuration#FailedThresholdCallback) 在达到最大重试次数时收到通知。
你可以在 CapOptions 中设置 [FailedRetryCount](configuration.md#failedretrycount) 来调整默认重试的总次数,或使用 [FailedThresholdCallback](configuration.md#FailedThresholdCallback) 在达到最大重试次数时收到通知。

当失败总次数达到默认失败总次数后,就不会进行重试了,你可以在 Dashboard 中查看消息失败的原因,然后进行人工重试处理。

Expand All @@ -128,7 +128,7 @@ CAP 接收到消息之后会将消息进行 Persistent(持久化), 有关

## 消息数据清理

数据库消息表中具有一个 ExpiresAt 字段表示消息的过期时间,当消息发送成功或者消费成功后,CAP会将消息状态为 Successed 的 ExpiresAt 设置为 1天 后过期,会将消息状态为 Failed 的 ExpiresAt 设置为 15天 后过期(可通过 [FailedMessageExpiredAfter](../configuration#failedmessageexpiredafter) 配置)。
数据库消息表中具有一个 ExpiresAt 字段表示消息的过期时间,当消息发送成功或者消费成功后,CAP会将消息状态为 Successed 的 ExpiresAt 设置为 1天 后过期,会将消息状态为 Failed 的 ExpiresAt 设置为 15天 后过期(可通过 [FailedMessageExpiredAfter](configuration.md#failedmessageexpiredafter) 配置)。

CAP 默认情况下会每隔**5分钟**将消息表的数据进行清理删除,避免数据量过多导致性能的降低。清理规则为 ExpiresAt 不为空并且小于当前时间的数据。 也就是说状态为Failed的消息(正常情况他们已经被重试了 50 次),如果你15天没有人工介入处理,同样会被清理掉。你可以通过 [CollectorCleaningInterval](../configuration#collectorcleaninginterval) 配置项来自定义间隔时间。
CAP 默认情况下会每隔**5分钟**将消息表的数据进行清理删除,避免数据量过多导致性能的降低。清理规则为 ExpiresAt 不为空并且小于当前时间的数据。 也就是说状态为Failed的消息(正常情况他们已经被重试了 50 次),如果你15天没有人工介入处理,同样会被清理掉。你可以通过 [CollectorCleaningInterval](configuration.md#collectorcleaninginterval) 配置项来自定义间隔时间。

4 changes: 2 additions & 2 deletions docs/content/user-guide/zh/monitoring/diagnostics.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,13 +65,13 @@ dotnet-counters monitor --process-id=25496 --counters=DotNetCore.CAP.EventCounte

其中 process-id 为 CAP 所属的进程Id。

![img](/img/dotnet-counters.gif)
![img](../../../img/dotnet-counters.gif)

### 在 Dashboard 中查看度量

你可以配置 `x.UseDashboard()` 来开启仪表盘以图表的形式查看 Metrics 指标。 如下图:

![img](/img/dashboard-metrics.gif)
![img](../../../img/dashboard-metrics.gif)


在 Realtime Metric Graph 中,时间轴会随着时间实时滚动从而可以看到发布和消费消息每秒的速率,同时我们可以看到消费者执行耗时以“打点”的方式在 Y1 轴上(Y0轴为速率,Y1轴为执行耗时)。
Expand Down
1 change: 1 addition & 0 deletions docs/content/user-guide/zh/storage/postgresql.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ NAME | DESCRIPTION | TYPE | DEFAULT
:---|:---|---|:---
Schema | 数据库架构 | string | cap
ConnectionString | 数据库连接字符串 | string |
DataSource | [Data source](https://www.npgsql.org/doc/basic-usage.html#data-source) | [NpgsqlDataSource](https://www.npgsql.org/doc/api/Npgsql.NpgsqlDataSource.html) |

### 自定义表名称

Expand Down
4 changes: 2 additions & 2 deletions docs/content/user-guide/zh/transport/aws-sqs.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,15 +33,15 @@ public void TestBar(DateTime value)

在 CAP 启动后,在 AWS SNS 中你将看到

![img](/img/aws-sns-demo.png)
![img](../../../img/aws-sns-demo.png)

### SQS

针对每个消费者组,CAP 将创建一个与之对应的 SQS 队列,队列的名称为配置项中 DefaultGroup 的名称,类型为 Standard Queue 。

该 SQS 队列将订阅 SNS 中的 Topic ,如下图:

![img](/img/aws-sns-demo.png)
![img](../../../img/aws-sns-demo.png)

!!! warning "注意事项"
由于 AWS SNS 的限制,当你减少订阅方法时,我们不会主动删除 AWS SNS 或者 SQS 上的相关 Topic 或 Queue,你需要手动删除他们。
Expand Down
2 changes: 1 addition & 1 deletion docs/content/user-guide/zh/transport/rabbitmq.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ services.AddCap(x =>

当需要从异构系统或者直接接收从RabbitMQ 控制台发送的消息时,由于 CAP 需要定义额外的头信息才能正常订阅,所以此时会出现异常。通过提供此参数来进行自定义头信息的设置来使订阅者正常工作。

你可以在这里找到有关 [头信息](../cap/messaging#异构系统集成) 的说明。
你可以在这里找到有关 [头信息](../cap/messaging.md#异构系统集成) 的说明。

用法如下:

Expand Down
2 changes: 1 addition & 1 deletion docs/readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,5 +14,5 @@ Web site made with [Material for MkDocs](https://squidfunk.github.io/mkdocs-mate

```
cd CAP/docs
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
```

0 comments on commit 5844985

Please sign in to comment.