Overview

Motadata APM Custom Instrumentation enables you to enrich application traces with business-specific context by integrating language-specific package APIs into your application.

This capability is allows developers to inject custom attributes into the currently active trace without disrupting existing auto-instrumentation or span lifecycle behavior.

Custom Instrumentation Concept

Motadata APM provides zero-code auto-instrumentation to capture technical telemetry such as HTTP calls, database queries, and framework-level operations. However, real-world observability requires more than technical visibility.

Custom Instrumentation extends this by allowing you to attach business-relevant attributes (such as order IDs, tenant IDs, workflow states, or feature flags) directly to traces. This transforms raw telemetry into business-aware observability, enabling faster troubleshooting, deeper analysis, and more meaningful insights.

Auto-instrumentation answers:

“What failed?”

Custom instrumentation answers:

“Which business transaction failed, for which customer, under what condition, and why?”

Use custom instrumentation when you need to:

• Correlate traces with business entities (orders, tenants, users).
• Detect business failures even when technical responses are successful.
• Analyze performance across customer segments or feature roll-outs.
• Enable precise filtering and search in APM Explorer.

info

These are some common use cases, but you can use custom instrumentation in many other scenarios wherever additional business or application context is required inside traces.

Custom instrumentation in Motadata APM is designed for API-based attribute injection using language-specific packages.

How It Works

Custom instrumentation follows a non-intrusive flow:

1. Motadata auto-instrumentation creates and manages traces.
2. Your application integrates the Motadata language-specific package.
3. Using the package API, custom attributes are added to the active span.
4. Attributes are attached in-process without modifying trace structure.
5. Enriched traces are exported via OTel pipeline.
6. Motadata APM automatically indexes the new attributes for analysis.

Use Cases

Transaction-Level Troubleshooting

Attach identifiers such as:

• order_id
• transaction_id
• payment_method

Outcome: Instantly locate specific transactions without log correlation.

Customer or Tenant-Based Analysis

Attach attributes such as:

• tenant_id
• customer_tier
• account_id

Outcome: Compare performance across customer segments and prioritize impact.

Business Logic Visibility

Attach attributes such as:

• workflow_step
• decision_path
• validation_status

Outcome: Detect business failures hidden behind successful HTTP responses.s

Feature Rollout Monitoring

Attach attributes such as:

• feature_flag
• experiment_group

Outcome: Measure impact of feature changes in real time.

Supported Language Packages

Motadata provides custom instrumentation packages for the following runtimes:

Language	Notes
Java	OTelbased, Maven/Gradle integration
Python	pip-based package
.NET	NuGet package
Node.js	npm package
PHP	Composer package

Each package is designed to align with the runtime’s native OTel instrumentation model.

Implementation Approach

To implement custom instrumentation:

1. Ensure auto-instrumentation is already configured and running.
2. Install the Motadata language-specific package.
3. Integrate the package into your application code.
4. Use package APIs to add attributes to the active span.
5. Deploy and validate in APM Explorer.

info

Custom instrumentation requires an active trace context. Without auto-instrumentation, attributes cannot be attached to traces. Even if the application continues to run normally with proper exception handling implemented by the client application developer, trace data will not be generated.

What You Can Add

Custom attributes should represent meaningful business context.

Examples:

• orderId
• TenantId
• customer.tier
• payment.method
• workflowstep1
• feature123flag

These attributes become searchable, filterable, and analyzable inside the APM Explorer.

note

The attribute key can contain only alphabets, numbers, and a dot (.).

Best Practices

To ensure scalable and consistent usage:

• Use standardized attribute naming.

• Keep attribute keys lowercase, as they are converted to lowercase by default.

• Attach attributes at the appropriate execution point.

• Avoid setting null values or empty strings for any key.

• Avoid excessive attributes, as adding a redundant attribute key overrides the last captured value.

• Align attribute design across services.

Business Impact

Capability	Outcome
Attach business attributes	Converts technical traces into business-aware insights
Search and filter traces	Faster troubleshooting and RCA
Segment analysis	Compare performance across users, tenants, or features
Precision alerting	Trigger alerts based on business conditions

Motadata Custom Instrumentation bridges the gap between technical monitoring and business observability. By integrating language-specific packages, you can enrich traces with business context without modifying the underlying tracing system.