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)中引用环境变量
{{.Env.ENV_VAR}}
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"
...
970
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
