Dynatrace monitoring as code

最新推荐文章于 2023-12-21 00:05:30 发布

michael.xue

最新推荐文章于 2023-12-21 00:05:30 发布

阅读量603

点赞数

分类专栏： Dynatrace

原文链接：https://github.com/dynatrace-oss/dynatrace-monitoring-as-code#conditional-naming-json

版权

Dynatrace 专栏收录该内容

6 篇文章 5 订阅

订阅专栏

Dynatrace monitoring-as-code

Monaco(monitoring as code)是一个自动部署工具。它可以自动把Dynatrace的监控配置部署到一个或者多个环境中。

Monitoring as Code

1. 安装Monaco

monaco是以二进制包发布。要安装它只需要下载你使用的系统对应的安装包，然后解压就可以了。
[下载地址]
可执行文件的名字是monaco，记得把monaco所在的目录加到操作系统的PATH中。

mv ~/Downloads/monaco /usr/local/bin/

2. 命令（CLI）

monaco使用命令行接口，通过指定参数来运行。这个工具执行时会去找指定的文件夹。所有的配置工程(projects)都保存在这个文件夹里。如果命令行中没有特别指定，则当前文件夹为工作目录。

monaco --environments <path-to-environment-yaml-file> [--specific-environment <environment-name>] [--project <project-folder>] [--dry-run] [--verbose] [projects-root-folder]

如果只想部署工程文件夹中的某个工程，可以这样运行

monaco --project <project-folder> --environments <path-to-environment-yaml-file> [projects-root-folder]

上面的例子中，"project-folder"是在 "projects-root-folder"目录中的子目录。

注意[projects-root-folder]需要写和monaco命令所在目录的相对目录

为了验证在前文件夹内的配置项目，可以这样运行：

monaco --dry-run --environments <path-to-environment-yaml-file>

为了部署所有的配置工程到单个环境并得到详细输出，可以这样运行

monaco -v -e <path-to-environment-yaml-file> -se <name of environment>

指定多个配置工程的话可以用

-p="project1,project2,project3"

查看monaco的版本

monaco --version

支持的参数如下：

-d       
只验证配置项目格式不真实部署。 (shorthand)
-dry-run 
只验证配置项目格式不真实部署。
-p string 
指定要部署的配置工程（文件夹），同时会部署有依赖关系的配置项目。 (shorthand)
-project string 
指定要部署的配置工程（文件夹），同时会部署有依赖关系的配置项目。 
-se string
指定部署环境 (from list)(shorthand)
-specific-environment string
指定部署环境 (from list)	  
-e string
强制使用包含环境的yaml文件部署(shorthand)
-environments string
强制使用包含环境的yaml文件部署
-v      
显示debug日志 (shorthand)
-verbose 
显示debug日志
-version
打印当前版本并退出

Dry Run(验证配置）
指定-dry-run参数后只检查你写的Dynatrace配置文件(JSON文件）和工程文件（yaml文件）是否可以正确的被解析和使用。

./monaco -dry-run --environments=project/sub-project/my-environments.yaml
2020/06/16 16:22:30 monaco v1.0.0
2020/06/16 16:22:30 Reading projects...
2020/06/16 16:22:30 Sorting projects...
...
2020/06/16 16:22:30 Config validation SUCCESSFUL

新命令模式(Experimental new CLI)
从1.2.0开始引入了一个新的命令模式。目前这个模式是在实验阶段。为了激活新的命令，要加一个环境变量 NEW_CLI=1

NEW_CLI=1 monaco

新的命令模式是基于多个命令的模式而不是单个命令加参数的方式。目前可以使用下面的命令：

deploy

这个命令基本上就是旧的monaco命令。它用来部署特定的配置到dynatrace环境中。参数基本和monaco的参数相同。
download

这个命令可以从Dynatrace tenant下载配置为monaco文件。您可以利用这个功能避免从零开始使用monaco配置Dynatrace

3. 部署配置到Dynatrace

这个工具可以以工程(projects)的方式部署单个或者多个配置到Dynatrace。一个工程(project)是一个文件夹。在工程文件夹里包含了定义好的配置文件，这些配置可以部署到单个或者多个Dynatrace环境中。通过–project(或者-p)可以指定配置工程。

运行工具

下面是一些例子：

monaco -e=environments.yaml (deploy all projects in the current folder to all environments)

monaco -e=environments.yaml -p="project" projects-root-folder (deploy projects-root-folder/project and any projects in projects-root-folder it depends on to all environments)

monaco -e=environments.yaml -p="projectA, projectB" projects-root-folder (deploy projects-root-folder/projectA, projectB and dependencies to all environments)

monaco -e=environments.yaml -se dev (deploy all projects in the current folder to the "dev" environment defined in environments.yaml)

如果project中包含子工程(sub-project)，那么所有的配置工程都会被部署。
如果project依赖同个根目录下的不同的projects，那么所有依赖的配置工程也会一并被部署。
部署配置的时候需要对应的dynatrace环境的API Token(s)，这个可以用变量的形式写在environment文件里。
如果要部署到environments.yaml文件中指定的某一个环境，则要使用-specific-environment或者-se这个参数：

monaco -e=environments.yaml -se=my-environment -p="my-environment" cluster

Environments文件

environments定义在environments.yaml文件中。一个environments.yaml文件包括下面几个部分

environment 名字
environment的URL
保存environment Token的变量名字
下面是一个定义了两个environment的例子

foo:
    - name: "foo"
    - env-url: "https://foo.example.com"
    - env-token-name: "FOO_TOKEN_ENV_VAR"

bar:
    - name: "bar"
    - env-url: "https://bar.dynatrace-managed.com/e/environmentid"
    - env-token-name: "BAR_TOKEN_ENV_VAR"

environments还可以分组，单个environment只能被分到某一个组里，不能同时分到多个组里。要指定组的名字用 group.environment这种格式，如下面的例子所示：

production.foo:
    - name: "foo"
    - env-url: "https://foo.dynatrace.com"
    - env-token-name: "FOO_TOKEN_ENV_VAR"

production.bar:
    - name: "bar"
    - env-url: "https://bar.dynatrace-managed.com/e/id"
    - env-token-name: "BAR_TOKEN_ENV_VAR"

4. 配置的组成结构

Projects

工程文件在projects文件夹中按工程名(project)排序。工程(project)文件夹中只包含

configurations
or another project(s)
这意味着可以把配置工程分组成多个文件夹。不支持在同一个文件夹合并projects和configuratioins。

配置JSON 模板

这个工具使用的json文件就是代表Dynatrace APIs接收或返回的json对象。
我们可以使用Dynatrace UI去生成一个新的config文件。在Dynatrace Configuration API界面我们可以通过GET方法下载对应的json文件。下载后需要做一下处理。在配置文件中不能包含：

entity’s id ，但是可以包含它的name。

name必须定义成变量
与环境相关的硬编码，比如引用其它自动部署工程的entities, tags,management-zones等

这些内容应该使用变量引用
空值(Empty/null)，当创建对象的时候可以有。

许多API GET方法会返回创建对象用不到的属性。可以忽略这些属性。比如dashboards中的tileFilter。

monaco会把这些文件当成模板，因此您可以在配置文件中使用下面形式的变量

{{ .variable }}

变量需要在相应的yaml文件中定义。

注意事项

Dashboard JSON

当在Dynatrace UI创建完dashboard后，它是私有dashboard，您需要修改它的属性或者直接修改json文件让它变成共享dashboard。

"dashboardMetadata": {
    "name": "{{ .name }}",
    "shared": true,
    "sharingDetails": {
      "linkShared": true,
      "published": true
    },
    "dashboardFilter": {
      "timeframe": "",
      "managementZone": {
        "id": "{{ .managementZoneId }}",
        "name": "{{ .managementZoneName }}"
      }
    }
  }

Calculated log metrics JSON

对Calculated Log Metrics来说有一点特殊，当您创建custom log metrics的时候，您配置的name需要写成log metric的metricKey。
（略）

Conditional naming JSON

因为在conditional naming API中没有name参数，需要映射{{ .name }}到displayName。
例如

{
  "type": "PROCESS_GROUP",
  "nameFormat": "Test naming PG for {Host:DetectedName}",
  "displayName": "{{ .name }}",
  ...
}

{
  "type": "HOST",
  "nameFormat": "Test - {Host:DetectedName}",
  "displayName": "{{ .name }}",
  ...
}

{
  "type": "SERVICE",
  "nameFormat": "{ProcessGroup:KubernetesNamespace} - {Service:DetectedName}",
  "displayName": "{{ .name }}",
  ...
}

配置类型 / APIs

每一个“配置类型文件夹”必须包含一个yaml文件和一个或多个json文件。yaml文件指定要创建的配置的名字和要使用哪个(些)json文件。json文件是要发送给Dynatrace API的有关配置的具体内容。 “配置类型文件夹”必须和monaco支持的配置类型一致（大小写敏感）。

projects/
        {projectname}/
                     {configuration type}/
                                         config.yaml
                                         config1.json
                                         config2.json

支持的配置类型和需要的Token权限如下

Configuration	Endpoint	Token Permission(s)
alerting-profile	/api/config/v1/alertingProfiles	Read Configuration & Write Configuration
anomaly-detection-metrics	/api/config/v1/anomalyDetection/metricEvents	Read Configuration & Write Configuration
app-detection-rule	/api/config/v1/applicationDetectionRules	Read Configuration & Write Configuration
application	/api/config/v1/applications/web	Read Configuration & Write Configuration
auto-tag	/api/config/v1/autoTags	Read Configuration & Write Configuration
aws-credentials	/api/config/v1/aws/credentials	Read Configuration & Write Configuration
calculated-metrics-log	/api/config/v1/calculatedMetrics/log	Read Configuration & Write Configuration
calculated-metrics-service	/api/config/v1/calculatedMetrics/service	Read Configuration & Write Configuration
conditional-naming-host	/api/config/v1/conditionalNaming/host	Read Configuration & Write Configuration
conditional-naming-processgroup	/api/config/v1/conditionalNaming/processGroup	Read Configuration & Write Configuration
conditional-naming-service	/api/config/v1/conditionalNaming/service	Read Configuration & Write Configuration
custom-service-java	/api/config/v1/service/customServices/java	Read Configuration & Write Configuration
dashboard	/api/config/v1/dashboards	Read Configuration & Write Configuration
extension	/api/config/v1/extensions	Read Configuration & Write Configuration
maintenance-window	/api/config/v1/maintenanceWindows	Deprecated: Configure maintenance windows
management-zone	/api/config/v1/managementZones	Read Configuration & Write Configuration
notification	/api/config/v1/notifications	Read Configuration & Write Configuration
request-attributes	/api/config/v1/service/requestAttributes	Read Configuration & Capture request data
request-naming	/api/config/v1/service/requestNaming	Read Configuration & Write Configuration
synthetic-location	/api/v1/synthetic/locations	Access problem and event feed, metrics, and topology & Create and read synthetic monitors, locations, and nodes
synthetic-monitor	/api/v1/synthetic/monitors	Create and read synthetic monitors, locations, and nodes

工程文件(YAML)的结构

每个配置都需要一个YAML文件，最少要包含一个唯一的名字。如下面的例子，定义的{config name}将成为一个变量。json中的内容会赋值给这个变量，dynatrace创建相应的对象后也会更新这个变量的属性，比如赋值其中的ID信息。在其它的YAML文件中可以用{config name}.id来引用其中的ID值。

config:
    - {config name} : "{path of config json template}"

{config name}:
    - name: "{a unique name}"

例如：projects/infrastructure/alerting-profile/profiles.yaml

config:
  - profile: "projects/infrastructure/alerting-profile/profile.json"

profile:
  - name: "profile-name"
[...]

跳过配置部署

可以使用预定义的skipDeployment参数跳过配置的部署：

my-config:
  - name: "My config"
  - skipDeployment: "true"

默认部署，但是当分组或分环境执行时跳过

my-config:
  - name: "My config"
  - skipDeployment: "true"

my-config.development:
  - skipDeployment: "false"

或者反过来

my-config:
  - name: "My config"
  - skipDeployment: "false"

my-config.environment:
 - skipDeployment: "true"

为单个环境或组指定配置

配置可以被覆盖或者扩展：

加上.{Environment}指定环境
加上.{GROUP}指定组

email:
    [...]

email.group:
    [...]

email.environment1:
    [...]

email.environment2:
    [...]

email.environment3:
    [...]

如果同时定义了组中和环境中的配置项目，环境中的配置项目将覆盖组中的配置项目。

引用其它配置内容

很多时候要自动配置的项目会依赖其它的配置内容，比如很多配置依赖于定义在projects/infrastructure/management-zone中的management-zone。monaco允许引用其它配置中的name或者id。可以使用如下的格式

{var} : "{name of the referenced configuration}.[id|name]"

比如projects/project-name/dashboard/dashboard.yaml中要引用在/projects/infrastructure/management-zone/zone.json中定义的id

- managementZoneId: "projects/infrastructure/management-zone/zone.id"

引用其它的json模板

json模板在工程文件(YAML)中定义
testproject/auto-tag/auto-tag.yaml:

config:
  - application-tagging-multiproject: "application-tagging.json"

application-tagging-multiproject:
  - name: "Test Application Multiproject"

上面的例子中application-tagging.json位于某个project的auto-tag文件夹下，所以可以使用相对路径。当您要在其它project引用同样的模板时，就需要定义json模板的路径了：

config:
  - application-tagging-multiproject: "/path/to/project/auto-tag/application-tagging.json"

application-tagging-multiproject:
  - name: "Test Application Multiproject"

这样可以避免我们定义一些重复的内容。当然，还可以多次引用一个模板

config:
  - application-tagging-multiproject: "/path/to/project/auto-tag/application-tagging.json"
  - application-tagging-tesproject: "/path/to/project/auto-tag/application-tagging.json"
  - application-tagging-otherproject: "/path/to/project/auto-tag/application-tagging.json"

application-tagging-multiproject:
  - name: "Test Application Multiproject"
  - param: "Multiproject parameter"

application-tagging-tesproject:
  - name: "Test Application Tesproject"
  - param: "Tesproject parameter"

application-tagging-otherproject:
  - name: "Test Application Otherproject"
  - param: "Otherproject parameter"

环境变量模板

除了json文件模板还可以在工程文件(YAML)和配置文件(JSON)中引用环境变量

development:
    - name: "Dev"
    - env-url: "{{ .Env.DEV_URL }}"
    - env-token-name: "DEV_TOKEN_ENV_VAR"

下面的例子是利用环境变量ALERTING_PROFILE_VALUE去设置alerting profile的值

{
  "name": "{{ .name }}",
  "rules": [
    {
      "type": "APPLICATION",
      "enabled": true,
      "valueFormat": null,
      "propagationTypes": [],
      "conditions": [
        {
          "key": {
            "attribute": "WEB_APPLICATION_NAME"
          },
          "comparisonInfo": {
            "type": "STRING",
            "operator": "CONTAINS",
            "value": "{{ .Env.ALERTING_PROFILE_VALUE }}",
            "negate": false,
            "caseSensitive": true
          }
        }
      ]
    }
  ]
}

注意：传到配置的环境变量不能包含=

插件配置

重要
如果定义了插件创建的metric相关的内容，要确保通过名字引用插件。只有这样才能确保插件先被创建。
不能引用插件的id，因为Dynatrace不会返回这个id
只能使用name

比如projects/example-project/anomaly-detection-metrics/numberOfDistributionInProgressAlert.json依赖于projects/example-project/plugin/custom.jmx.EXAMPLE-PLUGIN-MY-METRIC.json中定义的插件。

projects/example-project/anomaly-detection-metrics/example-anomaly.yaml中使用名字来引用插件

- metricPrefix: "projects/example-project/plugin/custom.jmx.EXAMPLE-PLUGIN-MY-METRIC.name"

然后像这样在json中构建metric-id

"metricId": "ext:{{.metricPrefix}}.metric_NumberOfDistributionInProgressRequests"

删除配置

自动配置还可以删除那些不再需要的配置内容。monaco会查找project根目录下的delete.yaml文件并且在部署结束后删除在这个文件中定义的配置。 delete.yaml应该按下面的格式定义，使用name而不是id去删除配置

delete:
  - "auto-tag/my-tag"
  - "custom-service-java/my custom service"
...