AWSインテグレーション

AWSインテグレーション設定の一覧

GET /api/v0/aws-integrations

APIキーに必要な権限

  • Read

応答

成功時

AWSインテグレーション設定の一覧が返却されます。

{
  "aws_integrations": [<aws_integration>, <aws_integration>, ...]
}

<aws_integration> は以下のキーを持つオブジェクトです。

KEY TYPE DESCRIPTION
id string AWSインテグレーション設定ID
name string AWSインテグレーション設定名
memo string AWSインテグレーション設定に関するメモ
key string / null AWS のアクセスキーID
roleArn string / null AWS IAMロールのリソース名(ARN)
externalId string / null 外部ID
region string AWS のリージョン名
includedTags string カンマ(,)句切されたタグのリスト
excludedTags string カンマ(,)句切された除外タグのリスト
services services 各AWSサービスのインテグレーション設定   

<services> は以下のキーを持つオブジェクトです。

{
  <awsServiceName>: {
    "enable": <enable>,
    "role": <role>,
    "excludedMetrics": [<metric>, <metric>, ...],
    "retireAutomatically": <retireAutomatically>
  },
  <awsServiceName>: {
    "enable": <enable>,
    "role": <role>,
    "excludedMetrics": [<metric>, <metric>, ...]
  },
  ...
}

<awsServiceName> には 各AWSサービスの識別子 が入ります。

KEY TYPE DESCRIPTION
enable boolean インテグレーション設定が有効かどうか
role string / null ロールの詳細名
excludedMetrics array[string] 除外するメトリック名のリスト
includedMetrics array[string] 取得するメトリック名のリスト

role は AWSインテグレーション設定の登録の項目の role と同じ。

excludedMetrics と includedMetrics はAWSインテグレーション設定ごとに、全てのサービスを通してどちらか一方のみが返ります。

EC2・RDS・ElastiCache の場合は、追加で以下のキーが設定されています。

KEY TYPE DESCRIPTION
retireAutomatically boolean 自動退役が有効かどうか

失敗時

STATUS CODE DESCRIPTION
401 APIキーが不正のとき

AWSインテグレーション設定の取得

GET /api/v0/aws-integrations/<awsIntegrationId>

APIキーに必要な権限

  • Read

応答

成功時

AWSインテグレーション設定の情報が返却されます。

フォーマットはAWSインテグレーション設定の一覧APIの <aws_integration> オブジェクトと同じ形式です。

失敗時

STATUS CODE DESCRIPTION
401 APIキーが不正のとき
404 指定されたIDのAWSインテグレーション設定が存在しないとき

AWSインテグレーション設定の登録

POST /api/v0/aws-integrations

APIキーに必要な権限

  • Read
  • Write

入力

以下のキーをもつオブジェクト。

KEY TYPE DESCRIPTION
name string AWSインテグレーション設定名*1
memo string AWSインテグレーション設定に関するメモ
key string [optional] AWS のアクセスキーID*2
secretKey string [optional] AWS のシークレットアクセスキー*2
roleArn string [optional] AWS IAM ロールのリソースネーム(ARN)*2
externalId string [optional] 外部ID*2
region string AWS のリージョン名
includedTags string カンマ(,)句切りされたタグのリスト*3
excludedTags string カンマ(,)句切りされた除外タグのリスト*3
services services 各サービスのインテグレーション設定

<services> は以下のようなオブジェクトです。

{
  <awsServiceName>: {
    "enable": <enable>,
    "role": <role>,
    "excludedMetrics": [<metric>, <metric>, ...]
  },
  <awsServiceName>: {
    "enable": <enable>,
    "role": <role>,
    "excludedMetrics": [<metric>, <metric>, ...]
  },
  ...
}

<awsServiceName> には 各AWSサービスの識別子 が入ります。

KEY TYPE DESCRIPTION
enable boolean インテグレーション設定の有効(true)/無効(false)
role string / null ロールの詳細名*4。ロールを指定しない場合は、 null を設定してください。
excludedMetrics array[string] [optional] 除外するメトリック名のリスト*5
includedMetrics array[string] [optional] 取得するメトリック名のリスト*5

EC2・RDS・ElastiCache の場合は、追加で以下のキーが設定できます。

KEY TYPE DESCRIPTION
retireAutomatically boolean [optional] 自動退役 の有効(true)/無効(false)。設定されなかった場合、無効扱いとなります。

あるAWSサービスに対する設定を省略した場合、そのAWSサービスはインテグレーション無効扱いとなります。 例えば、以下の入力例では、 EC2・ELB・ALB以外のAWSサービスはインテグレーション無効扱いとなり、メトリックは連携されません。

入力例

{
  "name": "example",
  "memo": "This is example integration",
  "roleArn": "arn:aws:iam::123456789012:role/MackerelRole",
  "externalId": "string",
  "region": "ap-northeast-1",
  "includedTags": "service:foo,service:bar",
  "excludedTags": "environment:staging",
  "services": {
    "EC2": {
      "enable": true,
      "role": "AWSService:EC2Role",
      "excludedMetrics": ["ec2.status_check_failed.instance"],
      "retireAutomatically": true
    },
    "ELB": {
      "enable": true,
      "role": "AWSService:ELBRole",
      "excludedMetrics": []
    },
    "ALB": {
      "enable": true,
      "role": null,
      "excludedMetrics": ["alb.request.count"]
    }
  }
}

*1 AWSインテグレーション設定名について

ひとつのオーガニゼーションの中に、同じ名前のAWSインテグレーション設定名を複数つくることはできません。

*2 AWSアクセス情報について

AWSインテグレーションの連携方法には2つの方法があります。

  1. MackerelのシステムのAWSアカウントからのアクセスのみを許可するIAMロールを設定し、AssumeRoleで認証する方法
  2. アクセスキーIDとシークレットアクセスキーを設定する方法

詳しくは、こちら をご覧ください。

連携方法によって、 key・secretKey・roleArn・externalId に設定する値が以下のように異なります。

連携方法1の場合

roleArn にIAMロールのリソース名、externalId に外部IDを設定する必要があります。

外部IDは Mackerel より発行されるIDです。

AWSインテグレーション外部IDの生成 APIを利用して発行することができます。

同一オーガニゼーション内であれば、同じ外部IDを持ったAWSインテグレーションを複数設定することができます。

連携方法2の場合

key にアクセスキーID、secretKey にシークレットアクセスキーを設定する必要があります。

  • ※ 上記どちらの連携方法においても、適切なアクセス権限が設定されている必要 があります。指定したIAMロールが存在しない、適切なアクセス権限が付与されていないなど、AWSアクセス情報が不正な場合、正常にメトリックが連携されない恐れがありますので、ご注意ください。

*3 タグ/除外タグについて

Mackerel ではAWSのタグを指定して、登録するホストを絞り込むことができます。

指定したタグが付与されたリソースのみをホストとして登録し、メトリックを収集します。除外するタグを指定すると、そのタグが付与されたリソースはホストとして登録しません。

タグを service:foo, service:bar のように指定すると、キーが service で値が foo またはキーが service で値が bar であるタグが付与されているリソースが対象となります。

詳しくは、 こちら をご覧ください。

*4 ロールの詳細名

ロールの詳細名は <service name>:<role name> というフォーマットの文字列です。

e.g. Hatena-Bookmark サービスの db-master ロールならHatena-Bookmark:db-master

*5 除外可能・取得可能なメトリック名について

excludedMetrics では各AWSサービスに対して、監視対象から除外するメトリック名のリストを設定します。

includedMetrics では各AWSサービスに対して、監視対象として明示的に指定するメトリック名のリストを設定します。

excludedMetrics と includedMetrics はAWSインテグレーション設定ごとに、全てのサービスを通してどちらか一方のみを指定できます。 同一のAWSインテグレーション設定内で、サービスごとに excludedMetrics と includedMetrics を混在させることはできません。 いずれの場合でも、監視が不要なサービスについてリクエストに含める必要はありません。

Mackerel の AWS インテグレーション設定ページの「新規メトリックを自動追加する」には、 excludedMetrics を指定するとオン、 includedMetrics を指定するとオフとして反映されます。

各AWSサービスで利用可能なメトリック名の一覧は、こちら でご確認いただけます。

もしくは、AWSインテグレーションの除外可能なメトリック名一覧 APIを利用して取得することも可能です。

応答

成功時

作成されたAWSインテグレーション設定が返却されます。

フォーマットはAWSインテグレーション設定の一覧APIの <aws_integration> オブジェクトと同じ形式です。

失敗時

STATUS CODE DESCRIPTION
400 入力が受け付けられないフォーマットだったとき
401 APIキーが不正のとき / APIキーに書き込み権限がないとき

AWSインテグレーション設定の更新

PUT /api/v0/aws-integrations/<awsIntegrationId>

APIキーに必要な権限

  • Read
  • Write

入力

AWSインテグレーション設定の登録と同様です。

ただし、 key・secretKey・roleArn・externalId に関しては、省略された場合に更新されません。 また、 key・secretKey・roleArn・externalId に null を指定して連携方法を替えることができます。 その他のキーに関しては上書き更新となります。

応答

成功時

更新されたAWSインテグレーション設定が返却されます。

フォーマットはAWSインテグレーション設定の一覧APIの<aws_integration>オブジェクトと同じ形式です。

失敗時

STATUS CODE DESCRIPTION
400 入力が受け付けられないフォーマットだったとき
401 APIキーが不正のとき / APIキーに書き込み権限がないとき
404 指定されたIDのAWSインテグレーション設定が存在しないとき

AWSインテグレーション設定の削除

DELETE /api/v0/aws-integrations/<awsIntegrationId>

APIキーに必要な権限

  • Read
  • Write

応答

成功時

削除されたAWSインテグレーション設定が返却されます。

フォーマットはAWSインテグレーション設定の一覧APIの<aws_integration>オブジェクトと同じ形式です。

失敗時

STATUS CODE DESCRIPTION
400 入力が受け付けられないフォーマットだったとき
401 APIキーが不正のとき / APIキーに書き込み権限がないとき
404 指定されたIDのAWSインテグレーション設定が存在しないとき

AWSインテグレーション外部IDの生成

POST /api/v0/aws-integrations-external-id

APIキーに必要な権限

  • Read
  • Write

応答

成功時

生成された外部IDが返却されます。

一度発行した外部IDは、当該外部IDが設定されたAWSインテグレーション設定が全て削除されない限り、同一オーガニゼーション内であれば再利用することができます。

{
  "externalId": <externalId>
}
KEY TYPE DESCRIPTION
externalId string 生成された外部ID

失敗時

STATUS CODE DESCRIPTION
400 入力が受け付けられないフォーマットだったとき
401 APIキーが不正のとき / APIキーに書き込み権限がないとき

AWSインテグレーションの除外可能なメトリック名一覧

GET /api/v0/aws-integrations-excludable-metrics

APIキーに必要な権限

  • Read

応答

成功時

{
  <awsServiceName>: [<metric>, <metric>, ...],
  <awsServiceName>: [<metric>, <metric>, ...],
  ...
}
KEY TYPE DESCRIPTION
<awsServiceName> array[string] 各AWSサービスの除外可能なメトリック名一覧

<awsServiceName> には 各AWSサービスの識別子 が入ります。

失敗時

STATUS CODE DESCRIPTION
401 APIキーが不正のとき

その他

AWSサービス識別子一覧

Mackerel で用いられる識別子（ID）とそれに対応するAWSサービス（AWS SERVICE）は以下の通りです。

ID AWS SERVICE
EC2 Amazon EC2
ELB Elastic Load Balancing
ALB Application Load Balancer
NLB Network Load Balancer
RDS Amazon RDS
Redshift Amazon Redshift
ElastiCache Amazon ElastiCache
SQS Amazon SQS
Lambda AWS Lambda
DynamoDB Amazon DynamoDB
CloudFront AWS CloudFront
APIGateway Amazon API Gateway
Kinesis Amazon Kinesis
S3 Amazon S3
ES Amazon OpenSearch Service
ECSCluster Amazon ECS
SES Amazon SES
States AWS Step Functions
EFS Amazon EFS
Firehose Amazon Kinesis Data Firehose
Batch AWS Batch
WAF AWS WAF
Billing AWS Billing
Route 53 Amazon Route 53
Connect Amazon Connect
DocDB Amazon DocumentDB
CodeBuild AWS CodeBuild
Athena Amazon Athena