AWS Integration

List AWS Integration Settings

GET /api/v0/aws-integrations

Required permissions for the API key

  • Read

Response

Success

Returns a list of AWS Integration settings.

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

<aws_integration> is an object that holds the following keys.

KEY TYPE DESCRIPTION
id string AWS Integration setting ID
name string AWS Integration setting name
memo string notes related to the AWS Integration setting
key string / null AWS access key ID
roleArn string / null AWS IAM role resource(ARN)
externalId string / null External ID
region string AWS region
includedTags string list of tags separated by commas(,)
excludedTags string list of excluded tags separated by commas(,)
services services integration settings of each AWS service   

<services> is an object that holds the following keys.

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

Enter the AWS service identifier in place of <awsServiceName>.

KEY TYPE DESCRIPTION
enable boolean whether integration settings are enabled
role string / null full role name
excludedMetrics array[string] list of excluded metrics
includedMetrics array[string] list of included metrics

This role is the same as the role in Register AWS Integration Settings.

Only one or the other of excludedMetrics and includedMetrics will be returned for each AWS integration settings across all services.

With EC2, RDS and ElastiCache, the following additional keys are configured.

KEY TYPE DESCRIPTION
retireAutomatically boolean whether automatic retirement is enabled

Error

STATUS CODE DESCRIPTION
401 when the API key is invalid

Get AWS Integration Settings

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

Required permissions for the API key

  • Read

Response

Success

Returns information on the AWS Integration settings.

The format is the same as the object <aws_integration> in the List AWS Integration Settings API.

Error

STATUS CODE DESCRIPTION
401 when the API key is invalid
404 when AWS Integration settings for the specified ID do not exist

Register AWS Integration Settings

POST /api/v0/aws-integrations

Required permissions for the API key

  • Read
  • Write

Input

This object holds the following keys.

KEY TYPE DESCRIPTION
name string AWS Integration setting name*1
memo string notes related to the AWS Integration setting
key string [optional] AWS access key ID*2
secretKey string [optional] AWS secret access key*2
roleArn string [optional] AWS IAM role resource name(ARN)*2
externalId string [optional] External ID*2
region string AWS region
includedTags string list of tags separated by commas(,)*3
excludedTags string list of excluded tags separated by commas(,)*3
services services integration settings of each service

The object <services> is as shown below.

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

Enter the AWS service identifier in place of <awsServiceName>.

KEY TYPE DESCRIPTION
enable boolean whether integration settings are enabled(true)/disabled(false)
role string / null full role name*4. If not specifying a role, set to null.
excludedMetrics array[string] [optional] list of excluded metrics*5
includedMetrics array[string] [optional] list of included metrics*5

With EC2, RDS and ElastiCache, the following additional keys can be configured.

KEY TYPE DESCRIPTION
retireAutomatically boolean [optional] whether auto-retire is enabled(true)/disabled(false). If not configured, it will be treated as disabled.

If settings are omitted for a certain AWS service, the integration of that AWS service will be treated as disabled. In the example input below, AWS services other than EC2, ELB, and ALB will be treated as disabled and metrics will not be integrated.

Example input

{
  "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 About AWS Integration settings' names

Multiple AWS Integration settings of the same name cannot be created within the same organization.

*2 About AWS access information

There are two ways to integrate AWS integration.

  1. Set an IAM role that allows access only from the Mackerel system AWS account and authenticate with AssumeRole
  2. Set an access key ID and a secret access key

Refer here for more details.

Depending on the integration method, the values set for key, secretKey, roleArn, and externalId will differ in the following ways.

Integration method 1

Requires setting an IAM role resource name in roleArn and an external ID in externalId.

The external ID is an ID issued by Mackerel.

It can be issued using the Generate AWS Integration External ID API.

Multiple AWS integrations can be configured with the same external ID if within the same organization.

Integration method 2

Requires setting an access key ID in key and a secret access key in secretKey.

  • ※ In both of the above methods, it is required that you set adequate access permissions. Please note that if AWS access information is invalid, such as the specified IAM role not existing or access permissions not being granted, metrics may not integrate normally.

*3 About tags/excluding tags

In Mackerel, you can specify AWS tags to narrow down the hosts to register.

Only resources with the specified tag will be registered as a host and metrics collected. By specifying a tag to exclude, the resource with that tag will not be registered as a host.

If you specify the tag as service:foo, service:bar, this will target resources with a key of service and value of foo and those with a key of service and value of bar.

Refer here for more details.

*4 Full role name

The full name of a role is a string in the format of <service name>:<role name>.

e.g. Hatena-Bookmark service's db-master role looks like this Hatena-Bookmark:db-master

*5 About excludable / includable metrics

excludedMetrics sets a list of metric names to be excluded from monitoring for each AWS service.

includedMetrics sets a list of metric names to be explicitly included monitoring for each AWS service.

Only one or the other of excludedMetrics and includedMetrics can be set for each AWS integration settings across all services. Both excludedMetrics and includedMetrics can't coexist for each service within the same AWS integration settings. In either case, it is unnecessary to include services in request that you do not want to monitor.

On Mackerel's AWS integration settings page, "Add new metrics automatically" is enabled if you specify excludedMetrics, and is disabled if you specify includedMetrics.

Refer here for a list of metrics that can be used for each AWS service.

Alternatively, you can also obtain this using the List Excludable Metrics for AWS Integration API.

Response

Success

Returns registered AWS Integration settings.

The format is the same as the object <aws_integration> in the List AWS Integration Settings API.

Error

STATUS CODE DESCRIPTION
400 when the input is in an unacceptable format
401 when the API key is invalid / when the API key does not have writing permission

Update AWS Integration Settings

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

Required permissions for the API key

  • Read
  • Write

Input

This is the same as Register AWS Integration Settings.

However, key, secretKey, roleArn, and externalId will not be updated if omitted. Also, you can change the integration method by specifying null for key, secretKey, roleArn, and externalId. Other keys will be overwritten and updated.

Response

Success

Returns updated AWS Integration settings.

The format is the same as the object <aws_integration> in the List AWS Integration Settings API.

Error

STATUS CODE DESCRIPTION
400 when the input is in an unacceptable format
401 when the API key is invalid / when the API key does not have writing permission
404 when the AWS Integration setting of the specified ID does not exist

Delete AWS Integration Settings

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

Required permissions for the API key

  • Read
  • Write

Response

Success

Returns deleted AWS Integration settings.

The format is the same as the object <aws_integration> in the List AWS Integration Settings API.

Error

STATUS CODE DESCRIPTION
400 when the input is in an unacceptable format
401 when the API key is invalid / when the API key does not have writing permission
404 when the AWS Integration setting of the specified ID does not exist

Generate AWS Integration External ID

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

Required permissions for the API key

  • Read
  • Write

Response

Success

Returns a generated external ID.

Once issued, the external ID can be reused as long as it is within the same organization, unless all AWS Integration settings configured with the external ID are deleted.

{
  "externalId": <externalId>
}
KEY TYPE DESCRIPTION
externalId string generated external ID

Error

STATUS CODE DESCRIPTION
400 when the input is in an unacceptable format
401 when the API key is invalid / when the API key does not have writing permission

List Excludable Metrics for AWS Integration

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

Required permissions for the API key

  • Read

Response

Success

{
  <awsServiceName>: [<metric>, <metric>, ...],
  <awsServiceName>: [<metric>, <metric>, ...],
  ...
}
KEY TYPE DESCRIPTION
<awsServiceName> array[string] list of excludable metrics for each AWS service

Enter the AWS service identifier in place of <awsServiceName>.

Error

STATUS CODE DESCRIPTION
401 when the API key is invalid

Others

List of AWS Service Identifiers

Here is a list of the AWS services and their corresponding identifiers (ID) used in Mackerel.

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