CloudWatchApplicationSignals / Client / create_instrumentation_configuration

create_instrumentation_configuration¶

CloudWatchApplicationSignals.Client.create_instrumentation_configuration(**kwargs)¶

Creates a dynamic instrumentation configuration for a specific code or endpoint location within a service and environment. Configurations are immutable after creation.

For BREAKPOINT type configurations, they expire after 24 hours unless a shorter expiration is provided. For PROBE type configurations, they persist until explicitly deleted; an expiration cannot be set for PROBE configurations.

If a configuration already exists for the same service, environment, signal type, and location, this operation returns a conflict instead of overwriting it. Use attribute filters and capture settings to control where the instrumentation runs and which data is collected.

Request Syntax

response = client.create_instrumentation_configuration(
    InstrumentationType='BREAKPOINT'|'PROBE',
    Service='string',
    Environment='string',
    SignalType='SNAPSHOT',
    Location={
        'CodeLocation': {
            'Language': 'Java'|'Python'|'Javascript',
            'CodeUnit': 'string',
            'ClassName': 'string',
            'MethodName': 'string',
            'FilePath': 'string',
            'LineNumber': 123
        }
    },
    Description='string',
    ExpiresAt=datetime(2015, 1, 1),
    AttributeFilters=[
        {
            'string': 'string'
        },
    ],
    CaptureConfiguration={
        'CodeCapture': {
            'CaptureArguments': [
                'string',
            ],
            'CaptureReturn': True|False,
            'CaptureStackTrace': True|False,
            'CaptureLocals': [
                'string',
            ],
            'CaptureLimits': {
                'MaxHits': 123,
                'MaxStringLength': 123,
                'MaxCollectionWidth': 123,
                'MaxCollectionDepth': 123,
                'MaxStackFrames': 123,
                'MaxStackTraceSize': 123,
                'MaxObjectDepth': 123,
                'MaxFieldsPerObject': 123
            }
        }
    },
    Tags=[
        {
            'Key': 'string',
            'Value': 'string'
        },
    ]
)

Parameters:

InstrumentationType (string) –
[REQUIRED]

Type of instrumentation: BREAKPOINT (temporary) or PROBE (permanent)
Service (string) –
[REQUIRED]

The name of the service to instrument. This should match the service.name resource attribute reported by the application.
Environment (string) –
[REQUIRED]

The environment that the service is running in, such as eks:cluster-prod/namespace or ec2:production.
SignalType (string) –
[REQUIRED]

The telemetry signal type to emit for this instrumentation. The supported value is SNAPSHOT.
Location (dict) –
[REQUIRED]

The location where instrumentation should be applied. Specify a CodeLocation for code-level instrumentation.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: CodeLocation.
- CodeLocation (dict) –
  
  A code location for code-level instrumentation, including language, code unit, class, method, file path, and optional line number.
  - Language (string) – [REQUIRED]
    
    The programming language for this instrumentation point, such as Java, Python, or JavaScript.
  - CodeUnit (string) –
    
    The package, module, or namespace that contains the target code, for example com.amazon.payment or payment_service.
  - ClassName (string) –
    
    The class or type name that contains the method. This is required for Java and optional for Python module-level functions.
  - MethodName (string) –
    
    The method or function name to instrument, such as validateCreditCard or __init__.
  - FilePath (string) – [REQUIRED]
    
    The source file path relative to the project or source root, such as src/payment/PaymentProcessor.java or src/payment/PaymentProcessor.py.
  - LineNumber (integer) –
    
    The line number to instrument. Provide this to disambiguate overloaded methods and to target a specific line when needed.
Description (string) – An optional short description (up to 50 characters) that explains the purpose of this instrumentation.
ExpiresAt (datetime) – For BREAKPOINT: optional, defaults to 24 hours, must be between 5 min and 24 hours. For PROBE: not supported. PROBE configurations are permanent and persist until explicitly deleted.
AttributeFilters (list) –
Client-side filters that target specific instances. Each object in the array is AND-matched on its keys, and multiple objects are OR-matched to decide where to apply the instrumentation.
- (dict) –
  
  A string-to-string map of OpenTelemetry resource attributes and values that must all match for the instrumentation to run on an instance.
  - (string) –
    - (string) –
CaptureConfiguration (dict) –
[REQUIRED]

Specifies what to capture when the instrumentation point is hit. Specify CodeCapture for code-level capture settings.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: CodeCapture.
- CodeCapture (dict) –
  
  Capture settings for code-level instrumentation, including arguments, return values, stack traces, local variables, and safety limits.
  - CaptureArguments (list) –
    
    The function arguments to capture. Omit to capture defaults, use an empty list to capture none, use ["*"] to capture all arguments, or specify argument names to capture selectively (up to 10 entries).
    - (string) –
  - CaptureReturn (boolean) –
    
    Whether to capture the return value. Defaults to false.
  - CaptureStackTrace (boolean) –
    
    Whether to capture a stack trace when the instrumentation point is hit. Defaults to true.
  - CaptureLocals (list) –
    
    The local variables to capture by name. Omit or pass an empty list to capture none. You can specify up to 20 names.
    - (string) –
  - CaptureLimits (dict) – [REQUIRED]
    
    Safety limits that bound what is captured, including hit counts, string length, collection depth, and stack trace size.
    - MaxHits (integer) –
      
      The maximum number of times the instrumentation point can be hit before it is automatically disabled. Defaults to 100.
    - MaxStringLength (integer) –
      
      The maximum length of captured string values in characters. Strings longer than this are truncated. Defaults to 128.
    - MaxCollectionWidth (integer) –
      
      The maximum number of items to capture from any collection to prevent large payloads. Defaults to 10.
    - MaxCollectionDepth (integer) –
      
      The maximum nesting depth to traverse inside collections. Defaults to 3.
    - MaxStackFrames (integer) –
      
      The maximum number of stack frames to capture in stack traces. Defaults to 2.
    - MaxStackTraceSize (integer) –
      
      The maximum total size, in bytes, of a captured stack trace. Defaults to 1000.
    - MaxObjectDepth (integer) –
      
      The maximum depth for nested object traversal when capturing structured data. Defaults to 3.
    - MaxFieldsPerObject (integer) –
      
      The maximum number of fields to capture for any object. Defaults to 10.
Tags (list) –
An optional list of key-value pairs to associate with the instrumentation configuration. Tags can help you organize and categorize your resources.
- (dict) –
  
  A key-value pair associated with a resource. Tags can help you organize and categorize your resources.
  - Key (string) – [REQUIRED]
    
    A string that you can use to assign a value. The combination of tag keys and values can help you organize and categorize your resources.
  - Value (string) – [REQUIRED]
    
    The value for the specified tag key.

Return type:

dict

Returns:

Response Syntax

{
    'InstrumentationType': 'BREAKPOINT'|'PROBE',
    'Service': 'string',
    'Environment': 'string',
    'SignalType': 'SNAPSHOT',
    'Location': {
        'CodeLocation': {
            'Language': 'Java'|'Python'|'Javascript',
            'CodeUnit': 'string',
            'ClassName': 'string',
            'MethodName': 'string',
            'FilePath': 'string',
            'LineNumber': 123
        }
    },
    'LocationHash': 'string',
    'Description': 'string',
    'ExpiresAt': datetime(2015, 1, 1),
    'AttributeFilters': [
        {
            'string': 'string'
        },
    ],
    'CaptureConfiguration': {
        'CodeCapture': {
            'CaptureArguments': [
                'string',
            ],
            'CaptureReturn': True|False,
            'CaptureStackTrace': True|False,
            'CaptureLocals': [
                'string',
            ],
            'CaptureLimits': {
                'MaxHits': 123,
                'MaxStringLength': 123,
                'MaxCollectionWidth': 123,
                'MaxCollectionDepth': 123,
                'MaxStackFrames': 123,
                'MaxStackTraceSize': 123,
                'MaxObjectDepth': 123,
                'MaxFieldsPerObject': 123
            }
        }
    },
    'CreatedAt': datetime(2015, 1, 1),
    'ARN': 'string'
}

Response Structure

(dict) –
- InstrumentationType (string) –
  
  The type of instrumentation that was created, echoed from the request.
- Service (string) –
  
  The service name for the instrumentation configuration, echoed from the request.
- Environment (string) –
  
  The environment for the instrumentation configuration, echoed from the request.
- SignalType (string) –
  
  The telemetry signal type for the instrumentation configuration, echoed from the request.
- Location (dict) –
  
  The location where instrumentation is applied, echoed from the request.
  Note
  This is a Tagged Union structure. Only one of the following top level keys will be set: CodeLocation. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
  'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
  - CodeLocation (dict) –
    
    A code location for code-level instrumentation, including language, code unit, class, method, file path, and optional line number.
    - Language (string) –
      
      The programming language for this instrumentation point, such as Java, Python, or JavaScript.
    - CodeUnit (string) –
      
      The package, module, or namespace that contains the target code, for example com.amazon.payment or payment_service.
    - ClassName (string) –
      
      The class or type name that contains the method. This is required for Java and optional for Python module-level functions.
    - MethodName (string) –
      
      The method or function name to instrument, such as validateCreditCard or __init__.
    - FilePath (string) –
      
      The source file path relative to the project or source root, such as src/payment/PaymentProcessor.java or src/payment/PaymentProcessor.py.
    - LineNumber (integer) –
      
      The line number to instrument. Provide this to disambiguate overloaded methods and to target a specific line when needed.
- LocationHash (string) –
  
  A stable hash computed from the location that uniquely identifies this instrumentation point within the service, environment, and signal type.
- Description (string) –
  
  The optional description that was stored with the instrumentation configuration.
- ExpiresAt (datetime) –
  
  The timestamp after which this configuration is no longer served to clients. Present only for BREAKPOINT configurations; PROBE configurations do not expire.
- AttributeFilters (list) –
  
  The attribute filters returned with the configuration so SDKs can perform client-side targeting.
  - (dict) –
    
    A string-to-string map of OpenTelemetry resource attributes and values that must all match for the instrumentation to run on an instance.
    - (string) –
      - (string) –
- CaptureConfiguration (dict) –
  
  The capture settings that were stored for this instrumentation configuration.
  Note
  This is a Tagged Union structure. Only one of the following top level keys will be set: CodeCapture. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
  'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
  - CodeCapture (dict) –
    
    Capture settings for code-level instrumentation, including arguments, return values, stack traces, local variables, and safety limits.
    - CaptureArguments (list) –
      
      The function arguments to capture. Omit to capture defaults, use an empty list to capture none, use ["*"] to capture all arguments, or specify argument names to capture selectively (up to 10 entries).
      - (string) –
    - CaptureReturn (boolean) –
      
      Whether to capture the return value. Defaults to false.
    - CaptureStackTrace (boolean) –
      
      Whether to capture a stack trace when the instrumentation point is hit. Defaults to true.
    - CaptureLocals (list) –
      
      The local variables to capture by name. Omit or pass an empty list to capture none. You can specify up to 20 names.
      - (string) –
    - CaptureLimits (dict) –
      
      Safety limits that bound what is captured, including hit counts, string length, collection depth, and stack trace size.
      - MaxHits (integer) –
        
        The maximum number of times the instrumentation point can be hit before it is automatically disabled. Defaults to 100.
      - MaxStringLength (integer) –
        
        The maximum length of captured string values in characters. Strings longer than this are truncated. Defaults to 128.
      - MaxCollectionWidth (integer) –
        
        The maximum number of items to capture from any collection to prevent large payloads. Defaults to 10.
      - MaxCollectionDepth (integer) –
        
        The maximum nesting depth to traverse inside collections. Defaults to 3.
      - MaxStackFrames (integer) –
        
        The maximum number of stack frames to capture in stack traces. Defaults to 2.
      - MaxStackTraceSize (integer) –
        
        The maximum total size, in bytes, of a captured stack trace. Defaults to 1000.
      - MaxObjectDepth (integer) –
        
        The maximum depth for nested object traversal when capturing structured data. Defaults to 3.
      - MaxFieldsPerObject (integer) –
        
        The maximum number of fields to capture for any object. Defaults to 10.
- CreatedAt (datetime) –
  
  The server-generated creation timestamp for this instrumentation configuration.
- ARN (string) –
  
  ARN for the created instrumentation configuration

Exceptions

CloudWatchApplicationSignals.Client.exceptions.ValidationException
CloudWatchApplicationSignals.Client.exceptions.ThrottlingException
CloudWatchApplicationSignals.Client.exceptions.ServiceQuotaExceededException
CloudWatchApplicationSignals.Client.exceptions.ConflictException