From 77f2116e12f15cf2a887d0f9500864a7e7ec956b Mon Sep 17 00:00:00 2001 From: XIANG Yang Date: Sun, 12 Nov 2023 11:02:20 +0800 Subject: [PATCH] update imgs and autotagging docs --- docs/zh/01-about/02-architecture.md | 2 +- docs/zh/01-about/03-features.md | 2 +- .../04-auto-tagging/02-smart-encoding.md | 2 +- .../04-auto-tagging/03-meta-tags.md | 2 +- .../04-auto-tagging/04-custom-tags.md | 8 +- .../04-auto-tagging/05-process-tags.md | 4 +- .../06-additional-cloud-tags.md | 30 +++---- .../04-auto-tagging/07-cmdb-tags.md | 81 +++++++++++++++++++ 8 files changed, 105 insertions(+), 26 deletions(-) create mode 100644 docs/zh/05-features/04-auto-tagging/07-cmdb-tags.md diff --git a/docs/zh/01-about/02-architecture.md b/docs/zh/01-about/02-architecture.md index 21e1d759..137d86ac 100644 --- a/docs/zh/01-about/02-architecture.md +++ b/docs/zh/01-about/02-architecture.md @@ -15,7 +15,7 @@ DeepFlow 企业版拥有更多的软件组件，以提供更加完善的数据 DeepFlow 的名称来自于我们对实现可观测性的认知：**对每一次应用调用（Flow）的深度（Deep）洞察**。DeepFlow 中的所有可观测性数据都是以调用为核心组织的：原始的调用日志、聚合生成的应用性能指标和服务全景图、关联生成的分布式追踪火焰图，以及在每一个调用生命周期内的网络性能指标、文件读写性能指标、函数调用栈性能剖析等。我们认识到这些可观测性数据在采集和关联上的困难，使用 eBPF 技术实现了零侵扰（Zero Code）的数据采集，并利用智能编码（SmartEncoding）机制实现了所有数据的全栈（Full Stack）关联。 -![DeepFlow 基于 eBPF 技术实现零侵扰的全栈数据采集](https://yunshan-guangzhou.oss-cn-beijing.aliyuncs.com/pub/pic/2023091164febaf0c68bc.png) +![DeepFlow 基于 eBPF 技术实现零侵扰的全栈数据采集](https://yunshan-guangzhou.oss-cn-beijing.aliyuncs.com/pub/pic/202311046546371f08829.png) 除了能够利用 eBPF 技术零侵扰采集观测数据以外，DeepFlow 还支持集成主流的可观测性技术栈，例如支持作为 Prometheus、OpenTelemetry、SkyWalking、Pyroscope 等技术栈的存储后端，并提供 SQL、PromQL、OTLP Export 能力作为 Grafana、Prometheus、OpenTelemetry、SkyWalking 的数据源，使得开发者可以快速将其融入到自己的可观测性解决方案中。当作为存储后端时，DeepFlow 并不只是简单的存储数据，利用领先的 AutoTagging 和 SmartEncoding 机制，高性能、自动化的为所有观测信号注入统一的属性标签，消除数据孤岛，并增强数据的下钻切分能力。 diff --git a/docs/zh/01-about/03-features.md b/docs/zh/01-about/03-features.md index 05ddbfaa..ef4cc06d 100644 --- a/docs/zh/01-about/03-features.md +++ b/docs/zh/01-about/03-features.md @@ -16,7 +16,7 @@ permalink: /about/features **全景图直接体现出了 eBPF 零侵扰的优势，对比 APM 有限的覆盖能力，所有的服务都能出现在全景图中**。但 eBPF 获取的调用日志不能直接用于拓扑展现，DeepFlow 为所有的数据注入了丰富的标签，包括云资源属性、K8s 资源属性、自定义 K8s 标签等。通过这些标签可以快速过滤出指定业务的全景图，并且可以按不同标签分组展示，例如 K8s Pod、K8s Deployment、K8s Service、自定义标签等。**全景图不仅描述了服务之间的调用关系，还展现了调用路径上的全栈性能指标**，例如下图右侧为两个 K8s 服务的进程在相互访问时的逐跳时延变化。我们可以很快的发现性能瓶颈到底位于业务进程、容器网络、K8s 网络、KVM 网络还是 Underlay 网络。充足的中立观测数据是快速定界的必要条件。 -![DeepFlow 的全景图对比 APM Agent 获取的拓扑图](https://yunshan-guangzhou.oss-cn-beijing.aliyuncs.com/pub/pic/2023091164fec16f9c9ad.png) +![DeepFlow 的全景图对比 APM Agent 获取的拓扑图](https://yunshan-guangzhou.oss-cn-beijing.aliyuncs.com/pub/pic/2023110465463725dd5ff.png) 目前，DeepFlow 已经内置支持解析主流应用协议，包括 HTTP 1/2、HTTPS（Golang/openssl）、Dubbo、gRPC、SOFARPC、FastCGI、MySQL、PostgreSQL、Redis、MongoDB、Kafka、MQTT、DNS，未来还将扩展更多应用协议的支持。 diff --git a/docs/zh/05-features/04-auto-tagging/02-smart-encoding.md b/docs/zh/05-features/04-auto-tagging/02-smart-encoding.md index 30676db9..abaf31f2 100644 --- a/docs/zh/05-features/04-auto-tagging/02-smart-encoding.md +++ b/docs/zh/05-features/04-auto-tagging/02-smart-encoding.md @@ -5,7 +5,7 @@ permalink: /features/auto-tagging/smart-encoding DeepFlow 为所有观测数据自动注入资源、服务和业务标签。在一个典型的生产环境中，需要为一条数据自动注入的标签数可能多达 100+ 个。这些标签为后端存储带来了很大的压力，DeepFlow 领先的 SmartEncoding 机制创新的解决了此问题，使得性能开销显著降低。 -![DeepFlow 中的 SmartEncoding](https://deepflow.io/images/V3/V2-06-01.svg) +![DeepFlow 中的 SmartEncoding](https://yunshan-guangzhou.oss-cn-beijing.aliyuncs.com/pub/pic/202310096523b164952a5.png) SmartEncoding 依赖于对各类标签数据的编码和关联。首先 Agent 获取到字符串格式的标签并汇总到 Server 上，接下来 Server 会对所有的标签进行编码。在此之后，对观测数据的 SmartEncoding 过程包含三个阶段： - 采集阶段：Agent 为每一条观测数据自动注入 VPC（Integer）、IP、PID 标签 diff --git a/docs/zh/05-features/04-auto-tagging/03-meta-tags.md b/docs/zh/05-features/04-auto-tagging/03-meta-tags.md index ce19c383..2edf6bb0 100644 --- a/docs/zh/05-features/04-auto-tagging/03-meta-tags.md +++ b/docs/zh/05-features/04-auto-tagging/03-meta-tags.md @@ -1,5 +1,5 @@ --- -title: K8s 资源信息注入 +title: 基础资源标签 permalink: /features/auto-tagging/meta-tags --- diff --git a/docs/zh/05-features/04-auto-tagging/04-custom-tags.md b/docs/zh/05-features/04-auto-tagging/04-custom-tags.md index 5edf224a..bc69eaf7 100644 --- a/docs/zh/05-features/04-auto-tagging/04-custom-tags.md +++ b/docs/zh/05-features/04-auto-tagging/04-custom-tags.md @@ -1,5 +1,5 @@ --- -title: K8s 自定义 Label 注入 +title: 自定义资源标签 permalink: /features/auto-tagging/custom-tags --- @@ -19,18 +19,18 @@ DeepFlow 目前支持自动关联 K8s 自定义 Label 的资源包括： # K8s Annotation -DeepFlow 目前支持自动关联 K8s 自定义 Annotation 的资源包括： +DeepFlow（仅企业版）目前支持自动关联 K8s 自定义 Annotation 的资源包括： - 容器服务 - Pod # K8s Env -DeepFlow 目前支持自动关联 K8s 自定义 Annotation 的资源包括： +DeepFlow（仅企业版）目前支持自动关联 K8s 自定义 Annotation 的资源包括： - Pod # 云资源自定义标签 -DeepFlow 目前支持自动关联云资源自定义标签的资源包括： +DeepFlow（仅企业版）目前支持自动关联云资源自定义标签的资源包括： - 云服务器 支持的公有云厂商包括： diff --git a/docs/zh/05-features/04-auto-tagging/05-process-tags.md b/docs/zh/05-features/04-auto-tagging/05-process-tags.md index f6492a6c..1ebd5e82 100644 --- a/docs/zh/05-features/04-auto-tagging/05-process-tags.md +++ b/docs/zh/05-features/04-auto-tagging/05-process-tags.md @@ -1,5 +1,5 @@ --- -title: 进程信息标签 +title: 可选的进程信息标签 permalink: /features/auto-tagging/process-tags --- @@ -7,6 +7,8 @@ permalink: /features/auto-tagging/process-tags 默认情况下，DeepFlow 采集的所有观测数据中，auto\_instance 标签的最细粒度为 IP 地址所属的容器 Pod 或云服务器等资源。当希望为数据注入进程粒度的标签信息时，需要开启 Agent 的进程信息同步功能。 +此功能一般用于 Agent 运行于云服务器（而非 K8s Node）的场景。 + # 所有配置项的 Yaml 文档 具体来讲涉及到如下 agent group config（[最新的 Yaml 文档参考 GitHub](https://github.com/deepflowio/deepflow/blob/main/server/controller/model/agent_group_config_example.yaml)）： diff --git a/docs/zh/05-features/04-auto-tagging/06-additional-cloud-tags.md b/docs/zh/05-features/04-auto-tagging/06-additional-cloud-tags.md index 76c5b358..8ba0d9eb 100644 --- a/docs/zh/05-features/04-auto-tagging/06-additional-cloud-tags.md +++ b/docs/zh/05-features/04-auto-tagging/06-additional-cloud-tags.md @@ -5,7 +5,7 @@ permalink: /features/auto-tagging/additional-cloud-tags # 简介 -DeepFlow 除了能够主动调用云服务商的 API 以同步资源信息以外，还提供了一个 `domain-additional-resource` 的声明式接口以允许外部推送云资源信息。这种方式适用于 DeepFlow 缺乏内置支持的云服务商，以及私有云场景。 +DeepFlow 除了能够主动调用（拉取）云服务商、K8s apiserver 的 API 以同步资源信息以外，还提供了一个 `domain-additional-resource` 的声明式接口以允许外部服务推送额外的资源信息。这种方式适用于同步 DeepFlow 尚未支持的公有云资源、使用 DeepFlow 社区版同步私有云资源、以及同步 CMDB 中的业务标签等场景。 使用该 API 可推送的资源信息包括： - 可用区 @@ -13,6 +13,7 @@ DeepFlow 除了能够主动调用云服务商的 API 以同步资源信息以外 - 子网 - 服务器 - 云服务器 +- 自定义业务标签 - 负载均衡器 使用该 API 可推送的自定义标签包括： @@ -43,15 +44,15 @@ PUT ### body -| 名称 | 类型 | 是否必填 | 说明 | -| ---------- | ------------------- | -------- | --------------------------- | -| azs | AZ 结构体数组 | 否 | availability zone（可用区） | -| vpcs | VPC 结构体数组 | 否 | virtual private cloud | -| subnets | Subnet 结构体数组 | 否 | 子网 | -| hosts | Host 结构体数组 | 否 | 服务器 | -| chosts | Chost 结构体数组 | 否 | 云服务器 | -| cloud_tags | CloudTag 结构体数组 | 否 | | -| lbs | LB 结构体数组 | 否 | load balance | +| 名称 | 类型 | 是否必填 | 说明 | +| ---------- | ------------------- | -------- | ------------------------------------------------------------ | +| azs | AZ 结构体数组 | 否 | Availability Zone（可用区） | +| vpcs | VPC 结构体数组 | 否 | Virtual Private Cloud | +| subnets | Subnet 结构体数组 | 否 | 子网 | +| hosts | Host 结构体数组 | 否 | 服务器 | +| chosts | Chost 结构体数组 | 否 | 云服务器 | +| cloud_tags | CloudTag 结构体数组 | 否 | 一般用于注入业务标签，详见[注入 CMDB 中的标签](./cmdb-tags/) | +| lbs | LB 结构体数组 | 否 | Load Balancer | AZ 结构体 @@ -123,13 +124,8 @@ Vinterface 2 结构体 | ips | 字符串数组 | 是 | 例：["x.x.x.x"] | -CloudTag 结构体 -| 名称 | 类型 | 是否必填 | 说明 | -| ------------- | -------------- | -------- | -------------------------------------------------------- | -| resource_type | 字符串 | 是 | 可选：chost 和 pod_ns（pod namespace） | -| resource_name | 字符串 | 是 | 资源名，从 vm.name 或 pod_namespace.name 中获取 | -| domain_uuid | 字符串 | 是 | 云平台 UUID，从 vm.domain 或 pod_namespace.domain 中获取 | -| tags | Tag 结构体数组 | 是 | 需要打标签的信息 | +CloudTag 结构体：详见[注入 CMDB 中的标签](./cmdb-tags/)。 + Tag 结构体 | 名称 | 类型 | 是否必填 | 说明 | diff --git a/docs/zh/05-features/04-auto-tagging/07-cmdb-tags.md b/docs/zh/05-features/04-auto-tagging/07-cmdb-tags.md new file mode 100644 index 00000000..78352bd3 --- /dev/null +++ b/docs/zh/05-features/04-auto-tagging/07-cmdb-tags.md @@ -0,0 +1,81 @@ +--- +title: 注入 CMDB 中的业务标签 +permalink: /features/auto-tagging/cmdb-tags +--- + +当我们希望将 CMDB 中的业务标签信息与观测信号进行关联时，可以使用 DeepFlow 的 `domain-additional-resources` 声明式 API。该 API 的详细使用说明请参考[额外的云资源标签](./additional-cloud-tags/)章节，本章节主要介绍如何利用其中的 `cloud_tags` 资源同步 CMDB 中的业务标签。 + +通过该 API，我们可以实现如下的效果： +- 将**云服务器**的业务、应用、服务、负责人等标签注入至 DeepFlow 的所有观测信号中 +- 将 **K8s 命名空间**的业务、应用等标签注入至 DeepFlow 的所有观测信号中 + +# API 中的字段定义 + +CloudTag 结构体定义如下： +| 名称 | 类型 | 是否必填 | 说明 | +| ------------- | -------------- | -------- | -------------------------------------------------------- | +| resource_type | 字符串 | 是 | 可选：chost 和 pod_ns（pod namespace） | +| resource_name | 字符串 | 是 | 资源名，从 vm.name 或 pod_namespace.name 中获取 | +| domain_uuid | 字符串 | 是 | 云平台 UUID，从 vm.domain 或 pod_namespace.domain 中获取 | +| tags | Tag 结构体数组 | 是 | 需要打标签的信息 | + +其中，Tag 结构体的定义如下： +| 名称 | 类型 | 是否必填 | 说明 | +| ----- | ------ | -------- | ------------------------------------------------------- | +| key | 字符串 | 是 | 限制 255 字符，不支持空格、冒号、反引号、反斜杠、单引号 | +| value | 字符串 | 是 | 限制 255 字符，不支持空格、冒号、反引号、反斜杠 | + +# 调用示例 + +具体的调用方法请参考[额外的云资源标签](./additional-cloud-tags/)章节，本章节主要介绍其中的 cloud_tags 部分。 + +## 通过 HTTP API 调用 + +```bash +curl -XPUT -H "Content-Type:application/json" \ +${deepflow_server_node_ip}:${port}/v1/domain-additional-resources/ \ +-d@additional_resource.json +``` + +```json +{ + // 注意：本 API 为声明式 API，请注意携带 API 中的其他资源信息（若有） + // "azs": [], + // "vpcs": [], + // ... + + "cloud_tags": [ + { + "resource_type": "xxxx", + "resource_name": "xxxx", + "domain_uuid": "xxxx", + "tags": [ + { + "key": "xxxx", + "value": "xxxx" + } + ] + } + ], + + // ... +} +``` + +## 通过 deepflow-ctl 命令调用 + +```yaml +## 注意：本 API 为声明式 API，请注意携带 API 中的其他资源信息（若有） +#azs: [] +#vpcs: [] +#... + +cloud_tags: +- resource_type: xxxx # required. options: chost, pod_ns + resource_name: xxxx # required. (If there is a duplicate name, one will be chosen at random.) + domain_uuid: xxxx # required + subdomain_uuid: # optional. (Fill in this value if you need to set cloud tags for subdomain) + tags: # required + - key: xxxx # required. (Limited to 255 characters and does not support spaces, colon, back quotes, backslash, single quotes.) + value: xxxx # required. (Limited to 255 characters and does not support spaces, colon, back quotes, backslash.) +```