Skip to content
ALTR ALTR ALTR Documentation

Custom Audit Logs

Custom Audit Logs enable you to extend ALTR’s logging to include custom events, enabling bespoke logging and reporting use cases. For instance, custom audit logs can be used to track login events for a particular data source.

How to Configure and Use Custom Audit Logs

Section titled “How to Configure and Use Custom Audit Logs”

Custom audit logs are triggered by sending event information from a Snowflake user-defined function to a Snowflake external function. See ALTR’s Snowflake Integration documentation for more information on how ALTR integrates with Snowflake. These functions are created automatically for newly connected Snowflake accounts. If your Snowflake account was connected to ALTR prior to January 2024, please contact  support@altr.com  for instructions to configure custom audit logs.

Events can be submitted to ALTR manually through SQL or automatically though processes such as Snowflake tasks. Submitting events to ALTR involves calling the user-defined function with a batch of records. ALTR requires certain information for each event, including:

  • Event Type— a customer-defined event and is used to distinguish between different kinds of events
  • Content Type— ALTR currently supports “application/json”
  • Event Details— a JSON object describing the event. It can include any information relevant to your use case

Optionally, customers can send an event time. The format of this timestamp is milliseconds from epoch. If an event time is not specified, ALTR will use the time the event was submitted.

There is a 256kb limit to the size of custom audit submissions. If you have more than 256kb worth of data to send, consider breaking the information down into smaller requests.

Accessing Custom Audit Logs

Section titled “Accessing Custom Audit Logs”

Custom Audit Logs are accessible via ALTR’s Amazon S3 Log Export . To enable exporting of custom audit logs to an S3 bucket, contact ALTR Support .

ALTR indexes events in S3 based on the event time. This is typically the customer-supplied time, if available. If a customer-supplied time is not provided or the customer-supplied time is more than 3 days in the past, events are indexed based on when they were submitted to ALTR.

Example SQL for Submitting Custom Audit Logs

Section titled “Example SQL for Submitting Custom Audit Logs”

Below is example SQL for a Snowflake Task that records events from Snowflake’s Login History every hour. See Snowflake’s documentation for more information on using tasks.

CREATE OR REPLACE TASK LOGIN_AUDIT_TASK
  SCHEDULE = '60 MINUTE'
AS
    SELECT "ALTR_DSAAS_DB"."{YOUR_SCHEMA_NAME}"."{YOUR_FUNCTION_NAME}"(select ARRAY_AGG("event_details") WITHIN GROUP (ORDER BY "event_details" ASC) as "audit_array" from (select TO_JSON(OBJECT_CONSTRUCT_KEEP_NULL( 'event_details', "custom_audit_blob", 'event_time', "event_time", 'content_type', "content_type", 'event_type', "event_type"))  as "event_details" from (SELECT (TO_VARIANT(OBJECT_CONSTRUCT_KEEP_NULL(
      'event_type', event_type,
      'user_name', user_name,
      'client_ip', client_ip,
      'first_authentication_factor', first_authentication_factor,
      'second_authentication_factor', second_authentication_factor,
      'is_success', is_success,
      'error_code', error_code,
      'error_message', error_message,
      'event_time', event_timestamp
    ))) "custom_audit_blob",
     date_part('EPOCH_MILLISECOND',audit_table.event_timestamp) as "event_time" ,
    'LOGIN' as "event_type",
    'application/json' as "content_type"
    FROM TABLE(information_schema.login_history(TIME_RANGE_START => dateadd('hours', -1, CURRENT_TIMESTAMP()), CURRENT_TIMESTAMP())) audit_table
    ORDER BY event_timestamp DESC)));


-- The query below starts the automated task
ALTER TASK LOGIN_AUDIT_TASK RESUME;

The Schema and Function name should be replaced with the schema and function automatically created by ALTR in your Snowflake account.

To find YOUR_SCHEMA_NAME and YOUR_FUNCTION_NAME:

  1. Log into your ALTR account.

  2. Select SettingsPreferences in the Navigation menu.

  3. Click the Organization ID tab.

  4. Locate the ALTR Organization ID . Copy this ID and update the dashes (-) to underscores (_); this becomes YOUR_SCHEMA_NAME.

  5. Run the following SQL query to obtain the function name: This command returns a single row that provides the full name of your custom audit function.

    SHOW USER FUNCTIONS LIKE 'ALTR_CUSTOM_AUDIT_%' IN SCHEMA ALTR_DSAAS_DB.ALTR_DSAAS_<MODIFIED ORG ID>;
© 2026 ALTR Solutions, Inc.