PIX Business Events Extension

A Dynatrace Extension 2.0 that monitors PIX transactions from a MySQL/MariaDB database and converts them to Business Events through OpenPipeline.

Table of Contents

• Overview
• Extension Structure
• Configuration
• Certificate Setup
• Database SSL/TLS Configuration
• Deployment

---

Overview

This extension:

• Queries MySQL/MariaDB database every minute for PIX transaction data
• Sends data as logs to Dynatrace
• Uses OpenPipeline to convert logs to Business Events
• Does NOT retain logs (only Business Events are stored)

Data Sources:

• pix_started_events - PIX transactions initiated
• pix_received_events - PIX transactions received

---

Extension Structure

BusinessEventsExtension/
├── extension/
│   ├── extension.yaml                      # Main extension definition
│   ├── pix-to-bizevents.pipeline.json     # OpenPipeline configuration
│   └── pix-to-bizevents.source.json       # OpenPipeline routing/source
├── config/                                  # Extension activation configs
├── dist/                                    # Built extension packages
└── .vscode/
    └── developer.p12                        # Developer certificate

---

Configuration

Extension Configuration (extension.yaml)

name: custom:db.logspixbizevent.extension
version: 0.1.0
minDynatraceVersion: "1.331.0"

sqlMySql:
  - group: pix_started_events
    interval:
      minutes: 1
    ingest: log
    query: |
      SELECT 
        id, timestamp, e2eID, value,
        origin_account, destination_account,
        destination, bank, type, created_at,
        'pix_started' AS event_type
      FROM send_pix
      WHERE timestamp >= DATE_SUB(NOW(), INTERVAL 1 MINUTE)
      ORDER BY timestamp DESC

openpipeline:
  pipelines:
    - displayName: PIX to BizEvents Pipeline
      pipelinePath: pix-to-bizevents.pipeline.json
      configScope: logs
  sources:
    - displayName: PIX to BizEvents Source
      sourcePath: pix-to-bizevents.source.json
      configScope: logs

Activation Configuration Example

{
  "name": "MySQL PIX Monitoring",
  "extensionId": "custom:db.logspixbizevent.extension",
  "activation": {
    "remote": {
      "unified": {
        "enabled": true
      }
    }
  },
  "properties": {
    "sqlMySql.host": "database-instance.region.rds.amazonaws.com",
    "sqlMySql.port": 3306,
    "sqlMySql.username": "admin",
    "sqlMySql.password": "your-password",
    "sqlMySql.database": "business_events_test",
    "sqlMySql.useSSL": true,
    "sqlMySql.truststore": "sqlds_truststore"
  }
}

---

Certificate Setup

1. Generate Developer Certificates

These certificates are used to sign your extension so Dynatrace trusts it.

Generate Certificates using VS Code Extension

The Dynatrace VS Code extension provides a built-in command to generate developer certificates automatically.

1. Open Command Palette (Ctrl+Shift+P)
2. Run: Dynatrace Extensions: Generate certificates
3. The extension will create all necessary certificates

The generated certificates will be stored in the VS Code workspace storage directory. For example:

/home/ec2-user/.vscode-server/data/User/workspaceStorage/{workspace-id}/DynatracePlatformExtensions.dynatrace-extensions/certificates/

Generated files:

• ca.pem - Root CA certificate (public)
• ca.key - Root CA private key
• developer.pem - Developer certificate (public)
• developer.key - Developer private key
• developer.p12 - PKCS12 package for signing extensions

Locating Your Generated Certificates

To find where the certificates were generated on your system:

1. Check the VS Code output panel during certificate generation for the exact path

2. Common locations:

   • Linux: /home/{user}/.vscode-server/data/User/workspaceStorage/{workspace-id}/DynatracePlatformExtensions.dynatrace-extensions/certificates/
   • Windows: C:\Users\{user}\AppData\Roaming\Code\User\workspaceStorage\{workspace-id}\DynatracePlatformExtensions.dynatrace-extensions\certificates\
   • macOS: /Users/{user}/Library/Application Support/Code/User/workspaceStorage/{workspace-id}/DynatracePlatformExtensions.dynatrace-extensions/certificates/

3. Find your workspace-id:

   find ~/.vscode-server/data/User/workspaceStorage -name "certificates" -type d

2. Deploy Root Certificate to ActiveGate

The root CA certificate (ca.pem) must be copied to your ActiveGate so it can verify signed extensions.

Step 1: Transfer Certificate to ActiveGate Host

First, transfer the ca.pem file from your development machine to the ActiveGate server.

Using SCP (Linux/macOS):

# Replace {certificates-path} with the actual path from step 1
# Replace {activegate-host} with your ActiveGate hostname or IP

scp {certificates-path}/ca.pem {user}@{activegate-host}:/tmp/

Example:

scp ~/.vscode-server/data/User/workspaceStorage/abc123def456/DynatracePlatformExtensions.dynatrace-extensions/certificates/ca.pem \
  ec2-user@activegate-server.example.com:/tmp/

Alternative methods:

• WinSCP (Windows) - Use the graphical interface to transfer the file
• SFTP - Any SFTP client can be used
• rsync - For those who prefer rsync
• Any other file transfer method that can copy files to the ActiveGate server

Step 2: Copy Certificate to ActiveGate Directory

Connect to the ActiveGate server and copy the certificate to the correct directory:

# SSH into the ActiveGate server
ssh {user}@{activegate-host}

# Copy certificate to ActiveGate certificates directory
sudo cp /tmp/ca.pem /var/lib/dynatrace/remotepluginmodule/agent/conf/certificates/

Step 3: Set Permissions and Ownership

sudo chown dtuserag:dtuserag /var/lib/dynatrace/remotepluginmodule/agent/conf/certificates/ca.pem
sudo chmod 644 /var/lib/dynatrace/remotepluginmodule/agent/conf/certificates/ca.pem

Step 4: Restart ActiveGate

sudo systemctl restart dynatracegateway

Important Notes:

• Only the root certificate ca.pem needs to be copied to the ActiveGate
• The destination directory is /var/lib/dynatrace/remotepluginmodule/agent/conf/certificates/
• Ensure the certificate has correct permissions (644) and ownership (dtuserag:dtuserag)

3. Verify Certificate Configuration

The Dynatrace VS Code extension automatically uses the generated developer.p12 certificate when building and signing your extension. No additional configuration is needed in the project.

---

Database SSL/TLS Configuration

1. Download Database CA Certificate

For AWS RDS:

# Create certificates directory
sudo mkdir -p /certs
sudo chown $USER:$USER /certs

# Download AWS RDS global certificate bundle
curl -o /certs/global-bundle.pem \
  https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

For other databases, obtain the CA certificate from your database provider.

2. Create Java Truststore for Extension

The extension requires a Java KeyStore (JKS) file containing the database CA certificate.

Check if Java keytool is available

which keytool
# If not found: sudo dnf install java-11-amazon-corretto

Import Database Certificate to Truststore

keytool -import -trustcacerts -noprompt \
  -alias database-ca \
  -file /certs/global-bundle.pem \
  -keystore sqlds_truststore \
  -storepass sqlds_truststore

Important parameters:

• -alias database-ca - Unique name for this certificate
• -keystore sqlds_truststore - Truststore filename (must match activation config)
• -storepass sqlds_truststore - Truststore password (must match config)

Verify Certificate Import

keytool -list -keystore sqlds_truststore -storepass sqlds_truststore

You should see the database-ca entry in the list.

3. Deploy Truststore to ActiveGate

Copy the truststore to the ActiveGate extension runtime directory:

# Copy truststore
sudo cp sqlds_truststore \
  /var/lib/dynatrace/remotepluginmodule/agent/conf/userdata/

# Set permissions
sudo chown dtuserag:dtuserag \
  /var/lib/dynatrace/remotepluginmodule/agent/conf/userdata/sqlds_truststore

sudo chmod 644 \
  /var/lib/dynatrace/remotepluginmodule/agent/conf/userdata/sqlds_truststore

4. Reference Truststore in Activation Config

In your extension activation configuration, reference the truststore:

{
  "properties": {
    "sqlMySql.useSSL": true,
    "sqlMySql.truststore": "sqlds_truststore"
  }
}

5. Test Database Connection

Verify SSL connection works:

mysql -h database-host.rds.amazonaws.com \
  -P 3306 -u admin \
  --password='your-password' \
  --ssl-verify-server-cert \
  --ssl-ca=/certs/global-bundle.pem \
  -e "SELECT VERSION();"

Expected output: Database version information

---

Deployment

1. Build Extension

Using Dynatrace VS Code extension:

1. Open Command Palette (Ctrl+Shift+P)
2. Run: Dynatrace: Build Extension
3. Extension package will be created in dist/

2. Upload to Dynatrace

Via Dynatrace Hub

1. Go to Dynatrace Hub > Extensions 2.0
2. Click Upload custom extension
3. Select the .zip file from dist/
4. Verify and confirm upload

Via API

curl -X POST "https://{environment-url}/api/v2/extensions" \
  -H "Authorization: Api-Token {api-token}" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @dist/custom-db.logspixbizevent.extension-0.1.0.zip

3. Create Monitoring Configuration

1. Go to Extensions 2.0 in Dynatrace
2. Find your extension: custom:db.logspixbizevent.extension
3. Click Add monitoring configuration
4. Configure:
   • Host/IP of database
   • Port (default: 3306)
   • Username/password
   • Database name
   • SSL settings and truststore reference

4. Verify Data Collection

After activation:

1. Check extension logs in ActiveGate:

   sudo tail -f /var/lib/dynatrace/remotepluginmodule/log/extensions/custom_db_logspixbizevent_extension/*.log

2. Query Business Events in Dynatrace:

   fetch bizevents
   | filter event.provider == "custom:db.logspixbizevent.extension"
   | limit 100
   

3. Check for errors in the extension monitoring page

---

Troubleshooting

Extension Certificate Issues

Problem: Extension fails to load or sign

Solution:

1. Verify certificates were generated correctly using VS Code extension
2. Ensure ca.pem is copied to ActiveGate at /var/lib/dynatrace/remotepluginmodule/agent/conf/certificates/
3. Check file permissions (644) and ownership (dtuserag:dtuserag)
4. Restart ActiveGate after copying the certificate

Database SSL Connection Issues

Problem: ERROR 2026 (HY000): TLS/SSL error

Solution:

1. Verify certificate exists: ls -l /certs/global-bundle.pem
2. Re-download certificate if missing
3. Verify truststore is deployed to ActiveGate
4. Check truststore permissions (must be readable by dtuserag)

No Data in Dynatrace

Problem: Extension shows as running but no Business Events appear

Solution:

1. Check SQL queries return data
2. Verify OpenPipeline is configured correctly
3. Check extension logs for query failures
4. Ensure database user has SELECT permissions on tables

---

Additional Resources

• Dynatrace Extensions 2.0 Documentation
• Dynatrace VS Code Extension
• AWS RDS SSL/TLS Certificates
• Java KeyStore and TrustStore

---

License

Proprietary - Copyright © 2026

Author

Igor Osch Simões