newrelic/entity-definitions
GitHub: newrelic/entity-definitions
这是一个用于定义 New Relic 中实体类型及其配置的开源仓库，帮助用户从自定义遥测数据源生成可监控的实体。
Stars: 84 | Forks: 406
[](https://opensource.newrelic.com/oss-category/#community-plus)
# 实体定义
此仓库包含所有存在于 New Relic 中的实体类型及其配置。
通过对此仓库提出更改，您可以实现以下目标：
- 创建新的实体类型
- 从新的数据源（遥测数据、日志等）生成实体
- 通过黄金指标（[New Relic Lookout](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/core-concepts/new-relic-lookout-monitor-your-estate-glance/)、[工作负载](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/workloads/workloads-isolate-resolve-incidents-faster/) 等）和摘要指标（[实体浏览器](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/core-concepts/new-relic-explorer-view-performance-across-apps-services-hosts/)）更改实体在不同体验中的呈现方式
- 修改实体类型的摘要
- 修改实体的生命周期并使其可设置警报（有关此属性的更多信息，请参阅[生命周期](docs/entities/lifecycle.md)）
## 变更日志
所有显著更改都定义在[发布页面](https://github.com/newrelic/entity-definitions/releases)。
## 入门指南
对于新手，我们建议查看[创建实体类型示例](docs/entities/README.md)。
本文档将引导您从头开始创建实体类型。
如果您对仓库有经验，并正在寻找特定部分的文档：
- [GUID 规范](docs/entities/guid_spec.md)
- [合成](docs/entities/synthesis.md)
- [生命周期](docs/entities/lifecycle.md)
- [实体摘要](docs/entities/entity_summary.md)
- [黄金指标](docs/entities/golden_metrics.md)
- [黄金标签](docs/entities/golden_tags.md)
- [摘要指标](docs/entities/summary_metrics.md)
如果您有兴趣探索**实验性功能**，可以在此处找到它们：
- [关系合成](docs/relationships/relationship_synthesis.md)
## 验证
每当有通过拉取请求进行的贡献时，会自动执行一些验证，以检查提供的定义是否满足基本要求：
* 定义文件格式正确、无误或不缺少必填字段。
* 除非设置了条件以进行区分，否则不能从两个不同 Domain-Types 中同名属性提取*标识符*，以确保一个实体的条件不是另一个实体条件的超集。
您可以使用我们的 Docker 化验证器在本地执行验证：
```
docker compose run validate-definitions
```
请记住，如果您过去运行过此操作，可能需要重新构建镜像以获取验证更改。
```
docker compose build validate-definitions
```
阅读更多关于[当前验证](/validator/README.md)的信息。
## 部署到测试环境
可以通过文件覆盖执行仅限测试环境的更改。如果您需要某些更改仅临时应用于测试环境，请按照以下步骤操作：
1. 复制要覆盖的文件（例如 `definition.yml`）并在扩展名中添加 `.stg`（例如 `definition.stg.yml`）
2. 对 `.stg` 文件进行更改
3. 部署时，`.stg` 文件将在测试环境中替换原始文件，而原始文件将用于生产环境
覆盖可以应用于 `entity-types` 和 `relationships` 目录中的所有文件。覆盖文件与原始文件位于同一目录。
请注意，原始文件必须保持不变，以便不影响生产环境部署。一旦在测试环境中的测试结束，可以删除原始文件并移除 `.stg` 后缀，将其提升到生产环境。
当测试文件删除时，需要将文件复制为 `.stg` 并保留为空。示例：
`APM-APPLICATION-to-INFRA-HOST.stg.yml`
```
relationships: []
```
也可以通过添加 `.stg` 后缀来测试新定义，这样它们将仅部署在测试环境中。
必需的验证步骤：
1. 确保没有因覆盖而导致的文件引用中断
2. 验证覆盖的规则标识符与原始文件不同（例如 mySuperRule -> mySuperRuleStgOverride）
3. 如果覆盖更改幅度足够大，您可能需要考虑添加新的定义/规则
#### 如何跟踪覆盖更改
在任何时候，都可以对 `.stg` 文件和原始文件进行差异比较，以查找被覆盖的内容。
## 测试
您可以测试您的实体定义中的合成规则是否与预期的遥测数据匹配，从而生成预期的实体。为此，我们提供了添加测试数据的功能，这些数据将模拟遥测事件。每当有通过拉取请求进行的贡献时，测试数据会根据合成规则进行检查，确保您的更改是匹配的。
### 如何添加测试数据
1. 如果不存在，请在您的实体定义目录下创建一个名为 `tests` 的文件夹。如果已存在，则跳过此步骤。
即 `definitions/ext-pihole/tests/`
2. 构建一个或多个测试文件，这些文件代表将合成您域和类型实体的遥测数据。每个文件必须满足：
* 文件名是报告给 New Relic 的事件名称。即 `Log`、`CustomEvent`
* 文件名具有 `.json` 扩展名。即 `Log.json`、`CustomEvent.json`
* 文件内容是有效的 JSON，由对象数组组成，每个对象代表一个遥测数据点
**Log.json**
```
[
{
"attribute1": "value1"
},
{
"attribute1": "value1",
"attribute2": "value2",
"attribute3": "value3"
}
]
```
3. 正常创建您的拉取请求，测试将在后台执行。如果定义中的合成规则与测试数据不匹配，机器人将在拉取请求中通过解释性评论通知您。
有关测试数据的示例，请参阅 [ext-pihole 定义](https://github.com/newrelic/entity-definitions/tree/main/entity-types/ext-pihole/tests/)。
## 支持
仓库中提供的信息不足以解决您的疑问？请通过打开一个问题与团队联系！
**其他支持渠道**
* [New Relic 文档](https://docs.newrelic.com)：使用我们平台的全面指南
* [New Relic 社区](https://discuss.newrelic.com)：参与故障排除问题的最佳场所
* [New Relic 开发者](https://developer.newrelic.com/)：构建自定义可观测性应用程序的资源
* [New Relic 大学](https://learn.newrelic.com/)：面向各级 New Relic 用户的在线培训课程
* [New Relic 技术支持](https://support.newrelic.com/) 24/7/365 工单支持。阅读更多关于我们的[技术支持服务](https://docs.newrelic.com/docs/licenses/license-information/general-usage-licenses/support-plan)。
## 贡献
我们鼓励您添加新的实体类型！请记住，当您提交拉取请求时，您需要通过 CLA-Assistant 的点击许可签署 CLA。每个项目只需签署一次 CLA。
如果您有任何问题，或者需要代表公司执行我们的公司 CLA（如果您代表公司进行贡献），请给我们发送电子邮件至 opensource@newrelic.com。
**关于漏洞的说明**
正如我们的[安全政策](../../security/policy)所述，New Relic 致力于保护其客户及其数据的隐私和安全。我们相信，由安全研究人员提供协调披露并与安全社区合作是实现我们安全目标的重要手段。
如果您认为在此项目或任何 New Relic 的产品或网站中发现了安全漏洞，我们欢迎您并非常感谢您通过 [HackerOne](https://hackerone.com/newrelic) 向 New Relic 报告。
## 许可证
实体合成定义根据 [Apache 2.0](http://apache.org/licenses/LICENSE-2.0.txt) 许可证获得许可。
标签：API集成, APM, New Relic, 云监控, 可观测性, 实体定义, 实体管理, 工作负载, 开源, 摘要指标, 数据源, 数据集成, 日志, 映射, 生命周期, 监控, 社区贡献, 自定义脚本, 警报, 请求拦截, 遥测, 遥测数据, 配置, 黄金指标