doc: skywalking 说明文档

调用链路追踪/skywalking-agent说明文档.md

@@ -89,3 +89,13 @@ Java agent的所有插件都是可插拔的。在agent或第三方仓库的optio
 7.[自定义增强](https://skyapm.github.io/document-cn-translation-of-skywalking/zh/8.0.0/setup/service-agent/java-agent/Customize-enhance-trace.html) 基于描述文件对方法进行追踪，而不是通过写插件或修改源代码。
 
 8.Spring Cloud Gateway 2.1.x 插件. 只有当你在 Spring Gateway 端安装了插件时才开启此插件。
+
+## Bootstrap 类插件
+
+由于意外风险，所有 Bootstrap 插件都是可选的。Bootstrap 插件在 bootstrap-plugins 文件夹中提供. 若使用这些插件，您需要将目标插件 jar 文件放入 /plugins 中.
+
+现在，我们有以下已知的 Bootstrap 插件.
+
+JDK HttpURLConnection 插件. Agent 兼容 JDK 1.6+
+
+JDK Callable and Runnable 插件. Agent 兼容 1.6+

调用链路追踪/skywalking-告警说明.md

+#Apache SkyWalking告警
+
+Apache SkyWalking告警是由一组规则驱动，这些规则定义在config/alarm-settings.yml文件中。
+
+告警规则的定义分为三部分:
+
+1.告警规则。它们定义了应该如何触发度量警报，应该考虑什么条件。
+
+2.网络钩子:Webhook。当警告触发时，哪些服务终端需要被告知。
+
+3.gRPC钩子. 远程gRPC方法的主机和端口，告警触发后调用
+
+#告警规则
+
+SkyWalking 的发行版都会默认提供config/alarm-settings.yml文件，里面预先定义了一些常用的告警规则。如下：
+
+1.最近 3 分钟内服务平均响应时间超过 1 秒。 
+
+2.服务成功率在最近 2 分钟内低于80%。 
+
+3.服务响应时间在最近 3 分钟内低于 1000 毫秒. 
+
+4.服务实例在最近 2 分钟内的平均响应时间超过 1 秒。 
+
+5.端点平均响应时间在最近 2 分钟内超过1秒。 
+
+6.数据库访问平均响应时间在过去 2 分钟内超过 1 秒。 
+
+7.端点之间平均响应时间在最近 2 分钟内超过 1 秒。
+
+这些预定义的告警规则，打开config/alarm-settings.yml文件即可看到。其具体内容如下：
+
+```yaml
+rules:
+  # 规则唯一名称，必须以'_rule'结尾.
+  endpoint_percent_rule:
+    # 度量值为 long、double或int 类型
+    metrics-name: endpoint_percent
+    threshold: 75
+    op: <
+    # 评估度量标准的时间长度
+    period: 10
+    # 度量有多少次符合告警条件后，才会触发告警
+    count: 3
+    #检查多少次，告警触发后保持沉默，默认周期相同
+    silence-period: 10
+    
+  service_percent_rule:
+    metrics-name: service_percent
+    # [可选]默认，匹配此指标中的所有服务
+    include-names:
+      - service_a
+      - service_b
+    exclude-names:
+      - service_c
+    threshold: 85
+    op: <
+    period: 10
+    count: 4
+  service_resp_time_percentile_rule:
+    # 度量值为 long、double或int 类型
+    metrics-name: service_percentile
+    op: ">"
+    # 多种指标值的阈值。P50、P75、P90、P95、P99的阈值
+    threshold: 1000,1000,1000,1000,1000
+    period: 10
+    count: 3
+    silence-period: 5
+    message: Response time of service instance {name} is more than 1000ms in 2 minutes of last 10 minutes
+```
+
+除此之外，官方还提供了一个config/alarm-settings-sample.yml文件，该文件是一个告警规则的示例文件，里面展示了目前支持的所有告警规则配置项：
+
+```yaml
+# Sample alarm rules.
+rules:
+  # Rule unique name, must be ended with `_rule`.
+  endpoint_percent_rule:
+    # Metrics value need to be long, double or int
+    metrics-name: endpoint_percent
+    threshold: 75
+    op: <
+    # The length of time to evaluate the metrics
+    period: 10
+    # How many times after the metrics match the condition, will trigger alarm
+    count: 3
+    # How many times of checks, the alarm keeps silence after alarm triggered, default as same as period.
+    silence-period: 10
+    message: Successful rate of endpoint {name} is lower than 75%
+  service_percent_rule:
+    metrics-name: service_percent
+    # [Optional] Default, match all services in this metrics
+    include-names:
+      - service_a
+      - service_b
+    exclude-names:
+      - service_c
+    threshold: 85
+    op: <
+    period: 10
+    count: 4
+```
+
+告警规则配置项的说明：
+
+1.Rule name：规则名称，也是在告警信息中显示的唯一名称。必须以_rule结尾，前缀可自定义
+
+2.metrics-name：度量名称，取值为oal脚本中的度量名，目前只支持long、double和int类型。详见Official OAL script
+
+3.include-names：该规则作用于哪些实体名称，比如服务名，终端名（可选，默认为全部）
+
+4.exclude-names：该规则作不用于哪些实体名称，比如服务名，终端名（可选，默认为空）
+
+5.threshold：阈值，对于多个值指标，例如percentile，阈值是一个数组。像value1 value2 value3 value4 value5这样描述. 每个值可以作为度量中每个值的阈值。如果不想通过此值或某些值触发警报，则将值设置为 -。
+
+6.op： 操作符，目前支持 >、<、=
+
+7.period（周期）：多久告警规则需要被核实一下。这是一个时间窗口，与后端部署环境时间相匹配
+
+8.count（计数）：在一个Period窗口中，如果values超过Threshold值（按op），达到Count值，需要发送警报
+
+9.silence-period（静默时间）：在时间N中触发报警后，在TN -> TN + period这个阶段不告警。 默认情况下，它和Period一样，这意味着相同的告警（在同一个Metrics name拥有相同的Id）在同一个Period内只会触发一次
+
+10.message：告警消息
+
+
+## Webhook（网络钩子）
+
+Webhook可以简单理解为是一种Web层面的回调机制，通常由一些事件触发，与代码中的事件回调类似，只不过是Web层面的。由于是Web层面的，所以当事件发生时，回调的不再是代码中的方法或函数，而是服务接口。例如，在告警这个场景，告警就是一个事件。当该事件发生时，SkyWalking就会主动去调用一个配置好的接口，该接口就是所谓的Webhook。
+
+SkyWalking 的告警 Webhook 要求对等方是一个 Web 容器. 告警的消息会通过 HTTP 请求进行发送, 请求方法为 POST, Content-Type 为 application/json, JSON 格式基于 List<org.apache.skywalking.oap.server.core.alarm.AlarmMessage进行序列化的。
+
+JSON数据示例：
+```json
+[{
+    "scopeId": 1,
+    "scope": "SERVICE",
+    "name": "serviceA",
+    "id0": 12,
+    "id1": 0,
+    "ruleName": "service_resp_time_rule",
+    "alarmMessage": "alarmMessage xxxx",
+    "startTime": 1560524171000
+}, {
+    "scopeId": 1,
+    "scope": "SERVICE",
+    "name": "serviceB",
+    "id0": 23,
+    "id1": 0,
+    "ruleName": "service_resp_time_rule",
+    "alarmMessage": "alarmMessage yyy",
+    "startTime": 1560524171000
+}]
+```
+字段说明：
+
+1.scopeId、scope：所有可用的 Scope 详见 org.apache.skywalking.oap.server.core.source.DefaultScopeDefine
+
+2.name：目标 Scope 的实体名称
+
+3.id0：Scope 实体的 ID
+
+4.id1：保留字段，目前暂未使用
+
+5.ruleName：告警规则名称
+
+6.alarmMessage：告警消息内容
+
+7.startTime：告警时间，格式为时间戳
+
+## gRPCHook
+
+告警消息将使用 Protobuf 类型通过gRPC远程方法发送. 消息格式，以下文件定义了关键信息 oap-server/server-alarm-plugin/src/main/proto/alarm-hook.proto。
+
+协议的部分内容如下:
+
+```java
+message AlarmMessage {
+    int64 scopeId = 1;
+    string scope = 2;
+    string name = 3;
+    string id0 = 4;
+    string id1 = 5;
+    string ruleName = 6;
+    string alarmMessage = 7;
+    int64 startTime = 8;
+}
+```
+
+## 动态更新配置
+
+从6.5.0开始，可以通过[动态配置](https://skyapm.github.io/document-cn-translation-of-skywalking/zh/8.0.0/setup/backend/dynamic-config.html)在运行时动态更新报警设置 , 它将覆盖 alarm-settings.yml 中的设置.
+
+为了确定是否触发告警规则, SkyWalking 需要为每个告警规则缓存时间窗的指标, 如果任何属性 (metrics-name, op, threshold, period, count, etc.) 的规则改变, 滑动窗口将会毁坏和重建, 导致此告警规则重新启动.

调用链路追踪/skywalking安装部署文档.md

@@ -63,7 +63,7 @@ tar -zxvf apache-skywalking-apm-8.8.1.tar.gz
 ```yml
 #集群配置
 cluster:
-  # 默认配置为单机模式
+  # 选择哪一种集群模式,默认配置为单机模式
   selector: ${SW_CLUSTER:standalone}
   # 单机版
   standalone:
@@ -111,6 +111,162 @@ cluster:
     secretKey: ${SW_CLUSTER_NACOS_SECRETKEY:""}
 ```
 
+```yml
+# core核心配置
+core:
+  #配置选择
+  selector: ${SW_CORE:default}
+  default:
+    # 本服务的角色，包含3总类型，当数据量较大时，需要分角色部署，增加处理能力。
+    # Mixed: 混合模式，接收数据,1级汇总数据，2级汇总数据
+    # Receiver: 接收角色,数据接收，1级汇总数据，持久化，告警
+    # Aggregator: 聚合角色，2级汇总数据，持久化，告警
+    role: ${SW_CORE_ROLE:Mixed} # Mixed/Receiver/Aggregator
+    # 接收ip
+    restHost: ${SW_CORE_REST_HOST:0.0.0.0}
+    # 接收ip
+    restPort: ${SW_CORE_REST_PORT:12800}
+    # 服务路径
+    restContextPath: ${SW_CORE_REST_CONTEXT_PATH:/}
+    # 最小线程
+    restMinThreads: ${SW_CORE_REST_JETTY_MIN_THREADS:1}
+    # 最大线程
+    restMaxThreads: ${SW_CORE_REST_JETTY_MAX_THREADS:200}
+    # 线程空闲时间，超过关闭
+    restIdleTimeOut: ${SW_CORE_REST_JETTY_IDLE_TIMEOUT:30000}
+    # 接收器优先级
+    restAcceptorPriorityDelta: ${SW_CORE_REST_JETTY_DELTA:0}
+    # 接收队列大小
+    restAcceptQueueSize: ${SW_CORE_REST_JETTY_QUEUE_SIZE:0}
+    # grpc服务接收ip
+    gRPCHost: ${SW_CORE_GRPC_HOST:0.0.0.0}
+    # grpc服务接收端口
+    gRPCPort: ${SW_CORE_GRPC_PORT:11800}
+    # 最大并发连接数
+    maxConcurrentCallsPerConnection: ${SW_CORE_GRPC_MAX_CONCURRENT_CALL:0}
+    # 最大消息体
+    maxMessageSize: ${SW_CORE_GRPC_MAX_MESSAGE_SIZE:0}
+    # gRpc线程队列大小
+    gRPCThreadPoolQueueSize: ${SW_CORE_GRPC_POOL_QUEUE_SIZE:-1}
+    # gRpc线程队列
+    gRPCThreadPoolSize: ${SW_CORE_GRPC_THREAD_POOL_SIZE:-1}
+    # gRpc安全协议是否开启
+    gRPCSslEnabled: ${SW_CORE_GRPC_SSL_ENABLED:false}
+    # gRpc安全协议开启，密钥地址
+    gRPCSslKeyPath: ${SW_CORE_GRPC_SSL_KEY_PATH:""}
+    # gRpc安全协议开启，密钥地址
+    gRPCSslCertChainPath: ${SW_CORE_GRPC_SSL_CERT_CHAIN_PATH:""}
+    # gRpc安全协议开启，密钥地址
+    gRPCSslTrustedCAPath: ${SW_CORE_GRPC_SSL_TRUSTED_CA_PATH:""}
+    #采样率
+    downsampling:
+      - Hour
+      - Day
+    # 采样数据留存时间，超过自动删除。
+    # Turn it off then automatically metrics data delete will be close.
+    # 是否开启数据保持处理器，关闭则不删除采样数据
+    enableDataKeeperExecutor: ${SW_CORE_ENABLE_DATA_KEEPER_EXECUTOR:true} 
+    # 数据保持处理器执行频率，单位分钟，默认5分钟一次
+    dataKeeperExecutePeriod: ${SW_CORE_DATA_KEEPER_EXECUTE_PERIOD:5} 
+    # 数据保留时间，单位天
+    recordDataTTL: ${SW_CORE_RECORD_DATA_TTL:3}
+    # 分析数据保留时间，单位天
+    metricsDataTTL: ${SW_CORE_METRICS_DATA_TTL:7}
+    # 是否开启数据缓存，缓存度量数据1分钟以减少数据库查询，
+    # 如果OAP集群在那一分钟内发生变化，那么在那一分钟内，这些度量可能不准确。
+    enableDatabaseSession: ${SW_CORE_ENABLE_DATABASE_SESSION:true}
+    # 每个报告周期的前N条记录, unit is minute
+    topNReportPeriod: ${SW_CORE_TOPN_REPORT_PERIOD:10} 
+    # 额外的模型字段，用于在可视化工具中查看es数据，开启会增加一定的性能损耗。
+    activeExtraModelColumns: ${SW_CORE_ACTIVE_EXTRA_MODEL_COLUMNS:false}
+    # 服务名最大长度，服务名+实例名的最大长度必须小于200
+    serviceNameMaxLength: ${SW_SERVICE_NAME_MAX_LENGTH:70}
+    # 实例名最大长度，服务名+实例名的最大长度必须小于200
+    instanceNameMaxLength: ${SW_INSTANCE_NAME_MAX_LENGTH:70}
+    # 端点名最大长度，服务名+端点名（api）的最大长度必须小于240
+    endpointNameMaxLength: ${SW_ENDPOINT_NAME_MAX_LENGTH:150}
+    # 定义一组span标记键，这些键可以通过GraphQL进行搜索。
+    searchableTracesTags: ${SW_SEARCHABLE_TAG_KEYS:http.method,status_code,db.type,db.instance,mq.queue,mq.topic,mq.broker}
+    # 定义一组日志标记键，该键应该可以通过GraphQL进行搜索。
+    searchableLogsTags: ${SW_SEARCHABLE_LOGS_TAG_KEYS:level}
+```
+
+```yml
+# storage数据存储配置
+storage:
+  # 选择数据存储类型
+  selector: ${SW_STORAGE:elasticsearch7}
+  # es6版本配置
+  elasticsearch:
+    nameSpace: ${SW_NAMESPACE:""}
+    clusterNodes: ${SW_STORAGE_ES_CLUSTER_NODES:localhost:9200}
+    protocol: ${SW_STORAGE_ES_HTTP_PROTOCOL:"http"}
+    user: ${SW_ES_USER:""}
+    password: ${SW_ES_PASSWORD:""}
+    trustStorePath: ${SW_STORAGE_ES_SSL_JKS_PATH:""}
+    trustStorePass: ${SW_STORAGE_ES_SSL_JKS_PASS:""}
+    # 安全管理文件，内容包括用户名/密码，由第三方工具管理。
+    secretsManagementFile: ${SW_ES_SECRETS_MANAGEMENT_FILE:""} 
+    # 索引步长，默认1，每天一个索引
+    dayStep: ${SW_STORAGE_DAY_STEP:1} 
+    # 索引分片数
+    indexShardsNumber: ${SW_STORAGE_ES_INDEX_SHARDS_NUMBER:1} 
+    # 索引副本数
+    indexReplicasNumber: ${SW_STORAGE_ES_INDEX_REPLICAS_NUMBER:1} 
+    # 大数据集配置，当查询包含超数据集，下面三种配置可以提高新能
+    # 大数据存储索引保留天数，小于0则与dayStep一致。
+    superDatasetDayStep: ${SW_SUPERDATASET_STORAGE_DAY_STEP:-1} 
+    # 大数据存储分片因子，分片数为indexShardsNumber*superDatasetIndexShardsFactor
+    # 此因素也会影响Zipkin和Jaeger的踪迹。
+    superDatasetIndexShardsFactor:${SW_STORAGE_ES_SUPER_DATASET_INDEX_SHARDS_FACTOR:5} 
+    # 大数据索引副本数
+    superDatasetIndexReplicasNumber:${SW_STORAGE_ES_SUPER_DATASET_INDEX_REPLICAS_NUMBER:0} 
+    # 异步批量写库，默认1000条
+    bulkActions: ${SW_STORAGE_ES_BULK_ACTIONS:1000} 
+    # 同步批量写库，默认5w条
+    syncBulkActions: ${SW_STORAGE_ES_SYNC_BULK_ACTIONS:50000} 
+    # 按时间写库，默认10秒
+    flushInterval: ${SW_STORAGE_ES_FLUSH_INTERVAL:10} 
+    # 并发入库请求数
+    concurrentRequests: ${SW_STORAGE_ES_CONCURRENT_REQUESTS:2} 
+    # 结果最大数据量
+    resultWindowMaxSize: ${SW_STORAGE_ES_QUERY_MAX_WINDOW_SIZE:10000}
+    # 源数据查询最大数据量
+    metadataQueryMaxSize: ${SW_STORAGE_ES_QUERY_MAX_SIZE:5000}
+    # 分段查询最大数据量
+    segmentQueryMaxSize: ${SW_STORAGE_ES_QUERY_SEGMENT_SIZE:200}
+    # 任务查询最大条数
+    profileTaskQueryMaxSize: ${SW_STORAGE_ES_QUERY_PROFILE_TASK_SIZE:200}
+    # OAP分析器
+    oapAnalyzer: ${SW_STORAGE_ES_OAP_ANALYZER:"{\"analyzer\":{\"oap_analyzer\":{\"type\":\"stop\"}}}"} 
+    # OPA日志分析器
+    oapLogAnalyzer: ${SW_STORAGE_ES_OAP_LOG_ANALYZER:"{\"analyzer\":{\"oap_log_analyzer\":{\"type\":\"standard\"}}}"} # the oap log analyzer. It could be customized by the ES analyzer configuration to support more language log formats, such as Chinese log, Japanese log and etc.
+    # 高级配置
+    advanced: ${SW_STORAGE_ES_ADVANCED:""}
+```
+
+```yml
+# agent-analyzer ：接收探针代理配置
+agent-analyzer:
+  selector: ${SW_AGENT_ANALYZER:default}
+  default:
+    # 慢数据访问阀值，单位ms
+    slowDBAccessThreshold: ${SW_SLOW_DB_THRESHOLD:default:200,mongodb:100} 
+    # 开启采样率时，开启对错误分段数据全部保持，防止没有处理错误数据。
+    forceSampleErrorSegment: ${SW_FORCE_SAMPLE_ERROR_SEGMENT:true} 
+    # 分段状态分析策略
+    # FROM_SPAN_STATUS：任何一个span状态决定分段状态，只要一个span为Error则为Error，默认
+    # FROM_ENTRY_SPAN：入口span状态决定分段状态
+    # FROM_FIRST_SPAN：第一个span状态决定分段状态
+    segmentStatusAnalysisStrategy: ${SW_SEGMENT_STATUS_ANALYSIS_STRATEGY:FROM_SPAN_STATUS} 
+    # Nginx和外部代理无法获取到原始地址的，且端口不在范围内的，不会产生客户端实例关系。
+    noUpstreamRealAddressAgents: ${SW_NO_UPSTREAM_REAL_ADDRESS:6000,9000}
+    # 慢跟踪阀值，花费更多的时间进行采样，开启采样机，-1不对慢跟踪采样。
+    slowTraceSegmentThreshold: ${SW_SLOW_TRACE_SEGMENT_THRESHOLD:-1} 
+    # 可以被分析的文件，用“,”逗号分隔
+    meterAnalyzerActiveFiles: ${SW_METER_ANALYZER_ACTIVE_FILES:spring-sleuth.yaml}
+```
+