New Relic APM¶

1. 访问 https://newrelic.com/signup
2. 免费注册（无需信用卡）
3. 获取 LICENSE_KEY（格式：40个字符的字母数字串）
4. 查看 LICENSE_KEY：
   账号 → API Keys → License Key

# 方式一：pip 安装（推荐）
pip install newrelic

# 验证安装
python -c "import newrelic; print(newrelic.version)"

# 方式二：配合 requirements.txt
echo "newrelic" >> requirements.txt
pip install -r requirements.txt

# 生成 newrelic.ini 配置文件（替换 YOUR_LICENSE_KEY 为真实 key）
newrelic-admin generate-config YOUR_LICENSE_KEY newrelic.ini

# 生成的配置文件内容示例：
# [newrelic]
# license_key = YOUR_LICENSE_KEY
# app_name = My Python Application
# monitor_mode = true
# log_level = info

; newrelic.ini 关键配置项

[newrelic]
; 许可证密钥（必填）
license_key = YOUR_LICENSE_KEY

; 应用名称（显示在 New Relic 界面中）
app_name = My Bioinfo API

; 是否启用监控
monitor_mode = true

; 日志级别（info/debug/warning/error）
log_level = info

; 日志文件路径
log_file = /tmp/newrelic-python-agent.log

; 是否启用分布式追踪（推荐开启）
distributed_tracing.enabled = true

; 是否启用无限追踪（高精度，需要 New Relic Edge 端点）
; infinite_tracing.trace_observer_host = YOUR_TRACE_OBSERVER_HOST

; 事务追踪阈值（秒，超过此值的请求会记录详细追踪）
transaction_tracer.transaction_threshold = 0.5

; 慢 SQL 查询阈值（秒）
transaction_tracer.slow_sql_whitelist = false
slow_sql.enabled = true

# 方式一：使用包装脚本启动（推荐，零代码修改）
NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program python app.py

# Gunicorn 项目
NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn app:app

# uWSGI 项目
NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program uwsgi uwsgi.ini

# FastAPI / Uvicorn 项目
NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program uvicorn main:app --host 0.0.0.0

# 方式二：代码中手动初始化（适合需要精细控制的情况）
import newrelic.agent

# 在程序最开始初始化（必须在其他 import 之前）
newrelic.agent.initialize('newrelic.ini')  # 加载配置文件

# 或者通过环境变量配置（不需要 ini 文件）
# export NEW_RELIC_LICENSE_KEY=your_key
# export NEW_RELIC_APP_NAME="My App"
newrelic.agent.initialize()                # 从环境变量读取

# 使用包装脚本启动后，以下框架会被自动监控：
# - Django / Flask / FastAPI（HTTP 请求）
# - SQLAlchemy / psycopg2（数据库查询）
# - Redis / Memcache（缓存操作）
# - Celery（异步任务）
# - requests / httpx（外部 HTTP 调用）
# - logging（日志转发）

# 5 分钟内数据会出现在 New Relic UI 的 APM 模块

import newrelic.agent

# 方式一：装饰器标记（推荐）
@newrelic.agent.function_trace()  # 追踪这个函数的执行时间
def process_sample(sample_id):
    """处理生信样本"""
    # 你的业务逻辑
    pass

# 方式二：后台任务标记
@newrelic.agent.background_task(name='analyze-microbiome')  # 后台任务
def run_microbiome_analysis(sample_id):
    # 添加自定义属性（可在 NRQL 中查询）
    newrelic.agent.add_custom_attribute('sample_id', sample_id)
    newrelic.agent.add_custom_attribute('pipeline_version', '2.0')

    # 记录自定义事件（可创建自定义 Dashboard）
    newrelic.agent.record_custom_event('AnalysisStarted', {
        'sample_id': sample_id,
        'tool': 'qiime2',
    })

    # 模拟分析流程
    try:
        result = run_qiime2_pipeline(sample_id)
        newrelic.agent.record_custom_metric(
            'Custom/SampleProcessed', 1  # 计数器
        )
        return result
    except Exception as e:
        # 记录异常（会出现在 Errors 模块）
        newrelic.agent.notice_error()  # 自动捕获当前异常
        raise

# 方式三：上下文管理器（精确追踪代码块）
def process_data(data):
    # 追踪特定代码块的耗时
    with newrelic.agent.FunctionTrace(newrelic.agent.current_transaction(), 
                                       name='parse-fastq'):
        parsed = parse_fastq_file(data)
    return parsed

import newrelic.agent

# 记录数值指标（如样本处理速度）
newrelic.agent.record_custom_metric('Custom/SamplesPerHour', 42.5)

# 记录多个指标
metrics = [
    ('Custom/CPUUsage', 65.3),
    ('Custom/MemoryMB', 1024),
    ('Custom/QueueSize', 15),
]
for name, value in metrics:
    newrelic.agent.record_custom_metric(name, value)

-- ===== 基础语法 =====
-- NRQL = New Relic Query Language，类 SQL 语法
-- 基本结构：SELECT 指标 FROM 数据类型 WHERE 条件 SINCE 时间范围

-- ===== APM 常用查询 =====

-- 1. 查询平均响应时间（过去 1 小时）
SELECT average(duration)
FROM Transaction
WHERE appName = 'My Bioinfo API'
SINCE 1 hour ago

-- 2. 查询错误率
SELECT percentage(count(*), WHERE error IS true) AS 'Error Rate'
FROM Transaction
WHERE appName = 'My Bioinfo API'
SINCE 1 day ago

-- 3. 查询最慢的前 10 个接口
SELECT max(duration) AS 'Max Duration (s)'
FROM Transaction
WHERE appName = 'My Bioinfo API'
FACET name          -- 按接口名分组（GROUP BY name）
SINCE 1 hour ago
LIMIT 10

-- 4. 事务吞吐量（每分钟请求数）
SELECT rate(count(*), 1 minute) AS 'Requests/min'
FROM Transaction
TIMESERIES              -- 时序图（随时间变化）
SINCE 1 hour ago

-- 5. 数据库查询耗时分布
SELECT histogram(duration, 10, 20) AS 'Response Time Distribution'
FROM Transaction
WHERE appName = 'My Bioinfo API'
SINCE 1 day ago

-- ===== 日志查询 =====

-- 6. 查询错误日志
SELECT message, timestamp
FROM Log
WHERE level = 'ERROR'
AND entity.name = 'My Bioinfo API'
SINCE 1 hour ago
LIMIT 100

-- 7. 按日志级别统计
SELECT count(*)
FROM Log
FACET level             -- 按日志级别分组
WHERE entity.name = 'My Bioinfo API'
SINCE 1 day ago

-- ===== 基础设施查询 =====

-- 8. 服务器 CPU 使用率
SELECT average(cpuPercent) AS 'CPU %'
FROM SystemSample
FACET hostname           -- 按主机名分组
TIMESERIES
SINCE 30 minutes ago

-- 9. 内存使用率
SELECT average(memoryUsedPercent) AS 'Memory %'
FROM SystemSample
WHERE hostname = 'my-server-01'
TIMESERIES
SINCE 1 hour ago

-- ===== 自定义事件查询 =====

-- 10. 查询自定义事件（如分析任务）
SELECT count(*), average(duration)
FROM AnalysisStarted     -- 自定义事件类型
FACET sample_type
SINCE 1 day ago

1. 创建告警策略（Alert Policy）：
   New Relic UI → Alerts → Alert Policies → Create alert policy

2. 添加告警条件：
   - 错误率 > 5%（持续 5 分钟）
   - 响应时间 > 2 秒（持续 10 分钟）
   - CPU 使用率 > 90%（持续 5 分钟）

3. 配置通知渠道：
   - Email（邮件）
   - Slack（即时消息）
   - PagerDuty（值班通知）
   - Webhook（自定义 HTTP 回调）

# 通过 API 创建告警（自动化运维场景）
import requests

NERDGRAPH_URL = "https://api.newrelic.com/graphql"
API_KEY = "YOUR_USER_API_KEY"  # User API Key（不是 License Key）

# 使用 NerdGraph（GraphQL API）创建告警策略
query = """
mutation {
  alertsPolicyCreate(accountId: YOUR_ACCOUNT_ID, policy: {
    name: "Bioinfo API Alerts"
    incidentPreference: PER_CONDITION_AND_TARGET
  }) {
    id
    name
  }
}
"""

response = requests.post(
    NERDGRAPH_URL,
    headers={"API-Key": API_KEY},
    json={"query": query}
)
print(response.json())

在 New Relic UI 中设置 SLO（服务水平目标）：
1. APM → 你的应用 → Service Levels
2. 设置 SLI（服务水平指标）：
   - 可用性：成功请求 / 总请求 > 99.9%
   - 延迟：响应时间 < 500ms 的请求占比 > 95%
3. New Relic 自动计算错误预算（Error Budget）
   - 错误预算 = 允许不达标的时间额度
   - 例如：99.9% 可用性 = 每月允许 43.8 分钟不可用

# ===== 安装与配置 =====
pip install newrelic                              # 安装 Agent
newrelic-admin generate-config $KEY config.ini   # 生成配置文件

# ===== 启动应用 =====
NEW_RELIC_CONFIG_FILE=config.ini newrelic-admin run-program python app.py
NEW_RELIC_CONFIG_FILE=config.ini newrelic-admin run-program gunicorn app:app
NEW_RELIC_CONFIG_FILE=config.ini newrelic-admin run-program uvicorn main:app

# ===== 环境变量配置（无 ini 文件）=====
export NEW_RELIC_LICENSE_KEY=your_license_key
export NEW_RELIC_APP_NAME="My App"
export NEW_RELIC_DISTRIBUTED_TRACING_ENABLED=true
export NEW_RELIC_LOG_LEVEL=info

# ===== NRQL 速查 =====
# 数据类型（FROM 后面）：
# Transaction       请求事务
# TransactionError  请求错误
# Log               日志
# SystemSample      系统指标（CPU/内存）
# ProcessSample     进程指标
# NetworkSample     网络指标
# SyntheticCheck    合成监控检查

# 时间范围（SINCE 后面）：
# 30 minutes ago / 1 hour ago / 1 day ago / 1 week ago
# 特定时间：'2024-01-01 00:00:00'

# 聚合函数：
# average() count() max() min() sum() percentage() rate() uniqueCount()

# ===== 免费套餐限制 =====
# 100 GB/月 数据摄入
# 1 个全平台用户
# 8 天数据保留
# 无限基础用户