How to export logs to CSV
If you need to export/archive your DNS query logs externally, here is how you can do it.
Using Web Panel
If you're looking to manually export your DNS query logs, simply navigate to Activity Log section, choose the desired device from the drop down menu (or select All Devices) and click the export button.
Using API
If you're looking to automate this behavior using very basic scripting, here is how you do that.
- Generate an API token API Token
- See API Docs on how you use this token (via Authorization header)
- Execute an API call against your Analytics instance:
GET https://analytics-endpoint-id.analytics.controld.com/queries/historical/csv?endTs=xxxxx&startTs=yyyyy&deviceId=zzzzz
analytics-endpoint-id
= See below how to find yoursstartTs
= Starting unix timestamp of the time window you're interested in. Can go back max of 3 days.endTs
= Ending unix timestamp of the time window you're interested in. You can omit this field if you want up-to-the-second logs.deviceId
= Resolver ID of the desired device you want logs for. You can omit this field to get logs for all devices.
Example
Here is a quick example using curl.
Test-Box:~$ curl 'https://jfk-org01.analytics.controld.com/queries/historical/csv?endTs=1712341614&startTs=1712255214' \
--header 'Authorization: Bearer REDACTED_API_TOKEN'
timestamp,organisationId,userId,deviceId,clientId,question,questionCategory,action,actionTrigger,actionTriggerValue,actionSpoofTarget,protocol,rrType,statusCode,sourceIp,sourceASN,sourceISP,sourceCity,sourceCountryCode,answers,answerASN,answerISP,answerCity,answerCountryCode
2024-04-05T19:20:42Z,1lga4zf,,redacted,7f9288dc9265,woot.com,,1,default,,,doh,A,0,66.207.208.000,21949,Beanfield Technologies,Toronto,CA,54.159.166.9,14618,Amazon.com,Ashburn,US
2024-04-05T19:17:01Z,1lga4zf,,redacted,c22a3d3b46b6,connectivity-check.ubuntu.com,,1,default,,,doh,A,0,96.45.193.000,21949,Beanfield Technologies,Toronto,CA,185.125.190.98;185.125.190.17;185.125.190.48;185.125.190.96;185.125.190.97;91.189.91.49;91.189.91.96;91.189.91.97;91.189.91.98;91.189.91.48;185.125.190.18;185.125.190.49,41231,Canonical Group Limited,,GB
How to find your Analytics Endpoint ID
On the Activity Log section, open dev tools, search for Analytics and find the "historical" request. The subdomain that's circled is your Analytics Endpoint ID.
Fetch Sub-Organization Data
By default, an API token that is generated within the main organization will only query logs for devices that belong to the main organization. This means that data generated by devices within sub-organizations will not be returned.
In order for the API token to access data within sub-organizations, you need to append an additional header to the earlier API call: X-Force-Org-Id: xxxxxxx
where xxxxxxx
is the Org ID of the desired sub-organization. You can find this ID at the top of the My Organization page.
Updated 8 months ago