使用新的遗物Python Agent API解锁可观察性电源
#python #api #games

（该帖子最初出现在the New Relic Blog上，并由Rachel Foster撰写）

开放卷轴：初学的可观察性

对于那些每天处理监视和可观察性的人来说，对新遗物等工具的需求不仅是不费吹灰之力的，而且是不言而喻的。它不需要进一步的解释。

但这不是所有人。从高层管理人员一直到战es中的部队，都有很多人对监视的作用，what observability is，也许最重要的是，它将是什么？甚至看起来像。

可以肯定的是，有很多滑行甲板，屏幕屏幕镜头和演示站点展示了仪表板和功能。但是对于新手的可观察性，很容易在术语和书呆子旋钮中迷失方向。

在此博客中，您不仅可以学习可观察性解决方案提供的一些最常见的元素，还可以了解如何在开箱即用的配置时构建自定义解决方案适合您的需求。更重要的是，您会在这样做时会很开心。

这是因为我们将实际的游戏用作示例应用程序。您会看到，有很多例子从这里开始的伪造外卖网络应用程序，虽然他们肯定会显示一个有效的现实世界示例。真正的yawner。

如果听到我们的声音，您可以学习可观察性概念和技术并同时玩电子游戏？！？

我知道，对吗？！？

这就是这个示例的全部内容。我们将安装游戏，配置新遗物以监视它，然后完全出于研究目的，您可以理解游戏以查看仪表板上发布的统计信息。

角色背景故事

危险的戴夫（Danges Dave）是一款经典的1980年代侧滚风格游戏，许多人在应该做生产力的工作时花了几个小时玩。它是由约翰·罗梅罗（John Romero）创建的，他是同一位游戏设计师，他将沃尔芬斯坦（Wolfenstein）3D，厄运和地震带入了生活。

以及在示例之间能够在示例之间玩一两个级别的明显吸引力，还有另一个原因是将游戏作为我们的示例：游戏不是一类应用程序，特别容易监视的仪器。他们通常写的是共享资源，发射统计信息，甚至运行其他东西，而其他东西在同一台计算机上运行。通过使用危险的dave（出于我们的目的，我们将其称为数据驱动的Dave）提出了一个微妙的观点，即如果您可以在此处添加可观察性，可以将其添加到几乎任何业务应用程序中您可以想出的标准，定制的货架或家园。

，但最重要的是，我们使用危险的Dave游戏，因此您可以有一种有趣的方式来踢新的Relic监视，并展示仪器非WEB脚本，背景工作流程的容易，和功能，捕获和收集非标准指标，并以有意义的方式显示它们。

预告片：看到的是

我们意识到最佳方法是吸引您尝试以后在此博客中看到的技术，就是现在向您展示结果。就在这里。新遗物可以采用看起来像这样的游戏，

Playing Dangerous Dave

并显示这样的结果。

Image description

现在，请记住，对于您和Aaah来说，这不是这个特定仪表板的外观多么惊人。我们希望您认识到，我们收集和显示一系列遥测和数据类型，从最高分数（例如最高分数）到游戏过程中收集的单个项目的细分，每个物品的值都会有助于整体得分。稍后，我们甚至会向您展示该仪表板如何包含日志数据。这会很好！让我们开始。

作弊代码：追逐（场景）

如果您想要这样的令人惊叹的仪表板，但是不想经历我们将在下面描述的每个乐器的步骤怎么办？我们有个好消息，因为我们已经为您完成了所有繁重的工作。如果您遵循以下快速步骤，您将立即有一个自己的仪表板。

  1. 确保您有一个新的Relic帐户。您可以免费注册here。免费帐户包括100 GB/月免费的数据摄入，一个免费的全平台用户和无限的免费基本用户。
  2. 设置系统，以便它可以在命令行上使用PyGame模块运行Python。可以是一台笔记本电脑，虚拟机，云实例，甚至是像replit的在线IDE中的项目。
  3. 前往Rachel的Github（又名Devrel Dragon），创建Data Driven Dave回购的本地副本。
  4. 请按照readme.md文件中的步骤安装系统，并在您的新Relic帐户中安装仪表板。
  5. 玩游戏。

就是这样！玩游戏将将遥测数据发送到您的新遗物帐户。您可以在New Relic platform中探索应用程序数据。具体来说，您会注意到应用程序性能监视（APM）Summary，Transactions和Logs屏幕现在正在报告有关数据驱动的Dave游戏的数据。很酷，对吧？继续，花一些时间探索一点。

哦，哇。即使在旋转游戏之后，您仍在阅读吗？好吧，你是认真的。好吧，卷起​​袖子，让我们挖掘代码以查看我们如何将其拉开。

Ready Player One：开始使用Python的自定义乐器

New Resic在guided installation的过程中做得很好，可以使您浏览带有新帐户快速启动和运行所需的步骤。此过程中存在一些偏见，没有网络前端的应用程序可以通过裂缝掉落。我们将向您展示解决这个问题的方法。出于我们的目的，由于数据驱动Dave背后的原始代码是用Python编写的，因此我们将研究如何使用Python agent API自定义监视解决方案。

要启动，在您的代码中，您必须用指定的配置文件导入newRelic.agent模块和initialize。

import newrelic.agent

newrelic.agent.initialize('newrelic.ini') # This is required!

初始化呼叫设置了Python代理，但未用collector注册代理，该组件从新的Relic Agents收集数据。您应该尽快致电register_application，并在调用以后的代码中与处理顺序有关。

application = newrelic.agent.register_application(timeout=5) # Force New Relic agent registration

if __name__ == "__main__":
    main()

接下来，您可以使用Python代码装饰器来启动您的非WEB交易。通常，您可能会以最准确地反映transaction trace的功能级段的方式使用这些装饰器。例如：

import newrelic.agent

@newrelic.agent.function_trace()
def test_function_trace():
    pass

@newrelic.agent.datastore_trace("redis", "my_collection", "set")
def test_datastore_trace():
    pass

@newrelic.agent.external_trace("library","http://www.example.com","get")
def test_external_trace():
    pass

@newrelic.agent.background_task()
def main():
    test_function_trace()
    test_datastore_trace()
    test_external_trace()

if __name__ == "__main__":
    main()

但是，对于我们的游戏演示，我们想在APM中展示更多交易。因此，我们选择专门使用background_task装饰器。这是Main_fun.py的摘录：

@newrelic.agent.background_task()
def showScores(screen, tileset):
    pass

@newrelic.agent.background_task()
def savePlayerScore(player_score, screen, tileset):
    pass

@newrelic.agent.background_task()
def showCreditsScreen(screen, tileset):
    pass

def main():
    # Init pygame
    pygame.init()
    game_screen = Screen(SCREEN_WIDTH, SCREEN_HEIGHT)

最后，在代码末尾，请致电shutdown_agent关闭代理并将最终数据上传到收集器。

newrelic.agent.shutdown_agent(timeout=2.5) # Shutdown New Relic agent

，就这样，您将申请遥测数据发送到新遗物。

升级日志

您说什么，太容易了？好的！让我们将其提升到一个新的水平。

在没有Web前端的上面概述的后端代码中进行自定义仪器时，代理不会自动配置新的Relic logs in context。相反，您必须通过首先在newRelic.ini文件中启用日志装饰和转发来手动配置日志。

# This setting enables log decoration, the forwarding of log events,
# and the collection of logging metrics if these sub-feature
# configurations are also enabled. If this setting is false, no
# logging instrumentation features are enabled. This can also be
# set using the NEW_RELIC_APPLICATION_LOGGING_ENABLED environment
# variable.
application_logging.enabled = true

# If true, the agent captures log records emitted by your application
# and forwards them to New Relic. `application_logging.enabled` must
# also be true for this setting to take effect. You can also set
# this using the NEW_RELIC_APPLICATION_LOGGING_FORWARDING_ENABLED
# environment variable.
application_logging.forwarding.enabled = true

接下来，您需要使用所需的日志记录手动装饰代码。这是一些示例代码：

import logging

# Logging test
logging.basicConfig(level=logging.INFO)
logging.info('This is a sample info message')
logging.warning('This is a sample warning message')
logging.error('This is a sample error message')

对于数据驱动的dave示例，一个更有意义的日志消息可能是在新游戏开始时记录消息。

# Game start log message
logging.info('Game started')

您还可以将变量合并到日志消息中。例如，您可以在游戏结束时以玩家的最终分数记录消息。

# Write game final score to log
logging.info('Game ended with score %s', GamePlayer.score)

要了解有关Python登录并查看更多示例的更多信息，请查看Logging in Python。

一旦您在newRelic.ini文件中启用了代码并启用了日志转发，您将在玩游戏时开始在新的Relic Logs屏幕中看到日志数据。

Image description

您不仅会在主日志管理屏幕中看到您的日志以及所有其他日志数据，还会查看数据驱动的dave dave特定日志。

Image description

单击它们将打开一个滑块窗口，显示日志详细信息。

Image description

请注意，您在此处的日志详细信息中看到的属性。 /p>

Boss Battle：添加自定义活动

很高兴看到您仍然与我们同在。让我们通过引入自定义活动来加强挑战。以新的遗物术语，事件是一个离散的事件，该事件已报告给可查询的数据对象。通过创建自定义事件，您可以可视化并获取专门定义的数据并发送到新的Relic数据库（NRDB）的警报。

要更好地理解何时定义自定义事件，请考虑一个用例，您想在其中跟踪当前级别并在每次玩家达到游戏中的下一个级别时得分。为了实现这一目标，您可以定义一个称为Levelup的event_type，其中包括Current_level和Player_score作为参数。然后，您将使用代码中的record_custom_event装饰器定义自定义事件。

# Record custom New Relic event
event_type = "LevelUp"
params = {'current_level': current_level_number, 'player_score': GamePlayer.score}
newrelic.agent.record_custom_event(event_type, params, application=application)

同样，您也可以定义一个称为gamecomplete的自定义event_type，每当玩家完成游戏时跟踪相同的自定义属性。

# Record custom New Relic event
event_type = "GameComplete"
params = {'current_level': current_level_number, 'player_score': GamePlayer.score}
newrelic.agent.record_custom_event(event_type, params, application=application)

将该数据发送到NRDB，允许您像本示例一样以新的Relic查询语言（NRQL）编写查询，该示例返回游戏中获得的最大分数。

SELECT max(player_score) FROM GameComplete WHERE appName = 'Data Driven Dave'

或像此查询一样，它将显示每个游戏级别达到的最高分数。

SELECT max(player_score) AS 'Top Score' FROM LevelUp WHERE appName = 'Data Driven Dave'
FACET current_level AS 'Level'

要了解有关定义代码中的自定义事件的更多信息，请参见Introduction to custom events and attributes New Relic Documentation。

高分：在仪表板上显示您的自定义指标和日志

现在我们已经走了一圈。还记得当我们向您展示最终结果时，还记得这篇博客文章的开头吗？后来我们告诉您，也有一种方法可以将日志添加到仪表板中。好吧，让我们看一下如何使用前一步中创建的自定义指标创建仪表板。

。

您可以使用新遗物中的仪表板功能来为您的最重要数据创建自定义可视化，以推动见解并更好地了解您的应用程序，客户或业务。 get started with dashboards有多种方法。出于此博客文章的目的，让您假设您将使用新的Relic query builder来编写和运行NRQL查询，然后将结果添加到仪表板中。

如果您不觉得自己准备在NRQL深处潜水，那还可以。现在是停下来并去查看Rachel的博客文章Five things you need to know to get started with New Relic的好时机。具体来说，＃3 learn how to query your data将帮助您缓解该过程。准备继续前进时回到这里。

您已经看到了一些使用NRQL根据升级和Gamecomplete自定义事件报告游戏指标的示例。让我们看一下如何使用自定义事件在仪表板上添加表以显示每个项目的总数及其相关的总价值。

首先，您需要在class.py文件中创建一个称为CollectedItem的自定义事件。

def collectItem(self, item_pos, level):
    x = item_pos[0]
    y = item_pos[1]
    item = level.getNode(x, y)
    itemIsEquipment = False

    # If the item is an equipment, add it to the inventory
    if isinstance(item, Equipment):
        itemIsEquipment = True
        self.inventory[item.getId()] = 1

    # Increment score
    self.score += item.getScore()

    # Record custom New Relic event
    event_type = "CollectedItem"
    params = {'item.id': item.getId(), 'item.score': item.getScore(), 
    'item.type': item.getType(), 'item.isEquipment': itemIsEquipment, 
    'levelNumber': self.currentLevelNumber, 'item.gfx_id': self.gfx_id}
    newrelic.agent.record_custom_event(
        event_type, params, application=newrelic.agent.application())

    level.clearNode(x, y)

然后，您将能够查询该自定义事件以获取项目计数和项目得分的总和。

SELECT count(*) AS '# Collected', sum(`item.score`) AS 'Total Value' FROM CollectedItem 
FACET if(`item.id` = 'items', item.type, item.id) AS 'Item Collected' SINCE 1 hour AGO

现在，让我们看一下如何在仪表板上添加日志数据。您可以选择直接从logs UI添加图表和表格。在屏幕上查找 nrql 和添加到仪表板选项。或者，在查询构建器中您可以从日志事件类型中进行选择。

SELECT count(*) FROM Log WHERE entity.name = 'Data Driven Dave' FACET `level` SINCE 1 hour AGO TIMESERIES

Image description

要探索游戏仪表板的其他查询想法，请完成数据驱动Dave Repo的prerequisite步骤，以将示例仪表板导入您的帐户。然后，您将能够查看每个仪表板小部件后面的查询。

Image description

片尾

恭喜，您一直到最后！虽然我们没有任何史诗般的歌曲来滚动屏幕或怪异的情节扭曲，这会使您质疑这是否是一个梦想。我们可以提供的是无限的进一步冒险的机会。实际上，您可以将整个博客文章视为更多扩展的培训方任务，就像您在游戏开始时发现的那样，只是为了学习绳索。让我们总结一下您学到的东西。

首先，您了解到新的遗物指导的安装过程不是摄入数据的唯一方法。更重要的是，您了解到可以使用Python Agent API之类的工具来手动装饰您的代码并自定义您发送到NRDB的APM交易详细信息。

接下来，您学习了如何手动将有关后端应用程序的日志详细信息发送到新遗物。我们向您展示了如何配置newRelic.ini文件以启用日志装饰和转发，以及如何装饰代码以报告多个日志级别的日志消息。

从那里我们继续前进，您学习了如何定义自己的自定义事件详细信息并将其写入NRDB中的可查询对象。我们向您展示了几个用例，以帮助您了解何时向新遗物报告自定义事件的有意义。

最后，您学会了如何将所有这些信息集中到仪表板中，该信息突出显示了您可能想要跟踪的关键应用程序数据。重要的是要注意到，我们显示您也可以使用相同的查询来创建警报。例如，您可以设置警报，让您知道何时获得新的高分。但是，我们将对另一篇博客文章进行警报讨论。今天我们在这里做得足够了，您认为吗？

最重要的是，您发现学习可观察性可能很有趣！现在您可以证明您可以捕获和收集数据驱动Dave内部的指标，事件，日志和交易，您可以完全库存处理真正的对手的技能和工具：在您的生产环境中运行的所有应用程序和服务！