Merged PR 1060665: Add documentation from Sharepoint
Added some markdown files from documentation on https://microsoft.sharepoint.com/teams/1ds.sdk.cpp/SitePages - Getting started on Windows - Getting started on Mac OS X - Privacy Settings (Privtags and DiagLevels) - Using Fiddler on Mac OS X
This commit is contained in:
Miguel Casillas
Max Golovanov
Родитель
02e23cd154
Коммит
de1cb0b996
|
|
@ -0,0 +1,137 @@
|
|||
---
|
||||
layout: page
|
||||
title: Getting started with the 1DS SDK (Beta) for Linux (C++)
|
||||
sub_title:
|
||||
|
||||
---
|
||||
# **1. Using privacy tags on UTC mode **
|
||||
|
||||
In order to set privacy tags to an event on UTC mode, the C++ SDK exposes the functionality on it's API.
|
||||
|
||||
To be able to send an event on UTC mode you need to set CFG_INT_SDK_MODE flag on the LogManager configuration:
|
||||
|
||||
```cpp
|
||||
config[CFG_INT_SDK_MODE] = SdkModeTypes::SdkModeTypes_UTCCommonSchema;
|
||||
```
|
||||
|
||||
To set a tag in code you can use the following syntax using the SetProperty method:
|
||||
|
||||
```cpp
|
||||
EventProperties event(eventName);
|
||||
|
||||
std::string evtType = "My.Record.BaseType";
|
||||
event.SetName("MyProduct.TaggedEvent");
|
||||
event.SetType(evtType);
|
||||
event.SetProperty("result", "Success");
|
||||
event.SetProperty("random", rand());
|
||||
event.SetProperty("secret", 5.6872);
|
||||
event.SetProperty("seq", (uint64_t)i);
|
||||
event.SetProperty(COMMONFIELDS_EVENT_PRIVTAGS, PDT_BrowsingHistory);
|
||||
event.SetLatency(latency);
|
||||
logger->LogEvent(event);
|
||||
```
|
||||
|
||||
You can also use the syntax to fill a collection:
|
||||
|
||||
```cpp
|
||||
EventProperties event2("MyProduct.TaggedEvent2",
|
||||
{
|
||||
{ "result", "Success" },
|
||||
{ "random", rand() },
|
||||
{ "secret", 5.6872 },
|
||||
{ "seq", (uint64_t)i },
|
||||
{ COMMONFIELDS_EVENT_PRIVTAGS, PDT_BrowsingHistory }
|
||||
});
|
||||
logger->LogEvent(event2);
|
||||
```
|
||||
|
||||
Here is a list of the privacy flags available on UTC default behavior:
|
||||
|
||||
```cpp
|
||||
PDT_BrowsingHistory 0x0000000000000002u
|
||||
PDT_DeviceConnectivityAndConfiguration 0x0000000000000800u
|
||||
PDT_InkingTypingAndSpeechUtterance 0x0000000000020000u
|
||||
PDT_ProductAndServicePerformance 0x0000000001000000u
|
||||
PDT_ProductAndServiceUsage 0x0000000002000000u
|
||||
PDT_SoftwareSetupAndInventory 0x0000000080000000u
|
||||
```
|
||||
|
||||
The tag set on your event will show it the field ext.metadata.privTags. You can validate that using Telemetry Real Time Tool **[TRTT](https://osgwiki.com/wiki/Telemetry_Real-Time_Tool_(TRTT)**
|
||||
|
||||
|
||||
|
||||
|
||||
# **2. Diagnostic level filtering**
|
||||
|
||||
The C++ SDK has an API feature to filter events using the diagnostic level associated with it.
|
||||
|
||||
There are different ways you can make your diagnostic levels filtering work:
|
||||
|
||||
|
||||
You can set a filter for the default LogManager in your application using the _SetLevel()_ API to allow events to be sent.
|
||||
An event inherits the Logger level when sent. If you set the **COMMONFIELDS_EVENT_LEVEL** property for your event this will override the default level.
|
||||
When no level is specified neither at event nor logger, the LogManager level is used for filtering.
|
||||
|
||||
Here's an example on how to achieve Diagnostic Level filtering:
|
||||
|
||||
```cpp
|
||||
|
||||
auto& config = LogManager::GetLogConfiguration();
|
||||
//Setup your custom config
|
||||
//...
|
||||
|
||||
// Default diagnostic level for this Logger
|
||||
auto logger0 = LogManager::Initialize(TENANT_TOKEN, config);
|
||||
|
||||
// Inherit diagnostic level from parent (LogManager level)
|
||||
auto logger1 = LogManager::GetLogger();
|
||||
|
||||
// Set diagnostic level to ENHANCED for logger2
|
||||
auto logger2 = LogManager::GetLogger(TEST_TOKEN, "my_enhanced_source");
|
||||
logger2->SetLevel(DIAG_LEVEL_ENHANCED);
|
||||
|
||||
// Set diagnostic level to FULL
|
||||
auto logger3 = LogManager::GetLogger("my_full_source");
|
||||
logger3->SetLevel(DIAG_LEVEL_FULL);
|
||||
|
||||
// A set that specifies that nothing passes through level filter
|
||||
std::set<uint8_t> logNone = { DIAG_LEVEL_NONE };
|
||||
// Everything goes through
|
||||
std::set<uint8_t> logAll = { };
|
||||
// Only allow BASIC level filtering
|
||||
std::set<uint8_t> logBasic = { DIAG_LEVEL_BASIC };
|
||||
|
||||
auto filters = { logNone, logAll, logBasic };
|
||||
|
||||
// Example of how level filtering works
|
||||
size_t i = 0;
|
||||
// For each filter defined
|
||||
for (auto filter : filters)
|
||||
{
|
||||
// Specify diagnostic level filter for the default LogManager
|
||||
LogManager::SetLevelFilter(DIAG_LEVEL_DEFAULT, filter);
|
||||
// For every logger
|
||||
for (auto logger : { logger0, logger1, logger2, logger3 })
|
||||
{
|
||||
// Create an event without diagnostic level
|
||||
EventProperties defLevelEvent("My.DefaultLevelEvent");
|
||||
// Behavior is inherited from the current logger
|
||||
logger->LogEvent(defLevelEvent);
|
||||
|
||||
// Create an event and set level to BASIC
|
||||
// This overrides the logger level for filtering
|
||||
EventProperties basicEvent("My.BasicEvent");
|
||||
basicEvent.SetLevel(DIAG_LEVEL_BASIC);
|
||||
logger->LogEvent(basicEvent);
|
||||
|
||||
// Create an event and set level to FULL
|
||||
// This overrides the logger level for filtering
|
||||
EventProperties fullEvent("My.FullEvent");
|
||||
fullEvent.SetLevel(DIAG_LEVEL_FULL);
|
||||
logger->LogEvent(fullEvent);
|
||||
}
|
||||
}
|
||||
|
||||
LogManager::FlushAndTeardown();
|
||||
|
||||
```
|
||||
|
|
@ -69,20 +69,26 @@ target_link_libraries(sample1 ${MSEVENTS_SDK_LIB}/libmsevents.a curl z ${CMAKE_T
|
|||
|
||||
1. Include the main 1DS SDK (Beta) header file in your main.cpp by adding the following statement to the top of your app's implementation file.
|
||||
|
||||
```cpp
|
||||
```
|
||||
#include "LogManager.hpp"
|
||||
```
|
||||
|
||||
2. Introduce the 1DS SDK (Beta) namespace by adding the following statement after your include statements at the top of your app's implementation file.
|
||||
|
||||
```
|
||||
using namespace Microsoft::Applications::Events;
|
||||
```
|
||||
|
||||
1. Introduce the 1DS SDK (Beta) namespace by adding the following statement after your include statements at the top of your app's implementation file.
|
||||
3. Create the default LogManager instance for your project using the following macro in your main file:
|
||||
|
||||
```cpp
|
||||
using namespace Microsoft::Applications::Events;
|
||||
```
|
||||
LOGMANAGER_INSTANCE
|
||||
```
|
||||
|
||||
1. Initialize the 1DS SDK (Beta) events system, create and send a telemetry event, and then flush the event queue and shut down the telemetry
|
||||
4. Initialize the 1DS SDK (Beta) events system, create and send a telemetry event, and then flush the event queue and shut down the telemetry
|
||||
logging system by adding the following statements to your main() function.
|
||||
|
||||
```cpp
|
||||
```
|
||||
ILogger* logger = LogManager::Initialize("0123456789abcdef0123456789abcdef-01234567-0123-0123-0123-0123456789ab-0123");
|
||||
logger->LogEvent("My Telemetry Event");
|
||||
...
|
||||
|
|
|
|||
|
|
@ -0,0 +1,94 @@
|
|||
---
|
||||
layout: page
|
||||
title: Getting started with the 1DS SDK (Beta) for Linux (C++)
|
||||
sub_title:
|
||||
|
||||
---
|
||||
This tutorial guides you through the process of integrating the 1DS SDK (Beta) into your existing C++ Mac OS X app or service.
|
||||
|
||||
## **Mac OS X prerequisites and dependencies for building from source**
|
||||
|
||||
Prerequisites:
|
||||
|
||||
* Mac OS X 10.10+
|
||||
* XCode 8+
|
||||
|
||||
Dependencies:
|
||||
|
||||
* zlib
|
||||
* sqlite3
|
||||
* libcurl
|
||||
* gtest (optional)
|
||||
* gmock (optional)
|
||||
|
||||
_**Note:** Preferably use Homebrew to install missing packages._
|
||||
|
||||
## **Clone the repository**
|
||||
|
||||
1. Run `git clone https://msasg.visualstudio.com/DefaultCollection/Shared%20Data/_git/Aria.SDK.Cpp` to clone the repo.
|
||||
|
||||
2. You will be asked your credentials to clone the repo, use your username and password as entered on https://msasg.visualstudio.com/DefaultCollection/_usersSettings/altcreds
|
||||
|
||||
If you do not have those credentials, generate them and use the username and password that you enabled.
|
||||
|
||||
|
||||
## **Build the SDK from source**
|
||||
|
||||
1. Navigate to the directory where the SDK is located
|
||||
|
||||
2. Run the file build.sh to build the SDK, this will build the SDK along with Unit and Functional Tests.
|
||||
|
||||
To disable building the tests go to the CMakeLists.txt file on the root of the SDK directory and change:
|
||||
|
||||
```
|
||||
option(BUILD_UNIT_TESTS "Build unit tests" YES)
|
||||
option(BUILD_FUNC_TESTS "Build functional tests" YES)
|
||||
```
|
||||
|
||||
to:
|
||||
```
|
||||
option(BUILD_UNIT_TESTS "Build unit tests" NO)
|
||||
option(BUILD_FUNC_TESTS "Build functional tests" NO)
|
||||
```
|
||||
|
||||
_**Note:** In order to build from scratch all dependencies along with the SDK you need to run:_ ` ./build.sh clean`
|
||||
|
||||
3. The SDK will be installed under `usr/local/libaria.a`
|
||||
|
||||
## **Instrument your code to send a telemetry event**
|
||||
|
||||
1. Include the main 1DS SDK (Beta) header file in your main.cpp by adding the following statement to the top of your app's implementation file.
|
||||
|
||||
```
|
||||
#include "LogManager.hpp"
|
||||
```
|
||||
|
||||
2. Introduce the 1DS SDK (Beta) namespace by adding the following statement after your include statements at the top of your app's implementation file.
|
||||
|
||||
```
|
||||
using namespace Microsoft::Applications::Events;
|
||||
```
|
||||
|
||||
3. Create the default LogManager instance for your project using the following macro in your main file:
|
||||
|
||||
```
|
||||
LOGMANAGER_INSTANCE
|
||||
```
|
||||
|
||||
4. Initialize the 1DS SDK (Beta) events system, create and send a telemetry event, and then flush the event queue and shut down the telemetry
|
||||
logging system by adding the following statements to your main() function.
|
||||
|
||||
```
|
||||
ILogger* logger = LogManager::Initialize("0123456789abcdef0123456789abcdef-01234567-0123-0123-0123-0123456789ab-0123");
|
||||
logger->LogEvent("My Telemetry Event");
|
||||
...
|
||||
LogManager::FlushAndTeardown();
|
||||
```
|
||||
|
||||
_**Important!** Replace the place-holder application key value with the actual value of your application key._
|
||||
|
||||
*You're done! You can now compile and run your app, and it will send a telemetry event.*
|
||||
|
||||
|
||||
_**Note:** If you need a deeper look into how to use the 1DS C++ SDK there is a couple of folders with examples under Aria.SDK.Cpp/examples_
|
||||
|
||||
|
|
@ -0,0 +1,114 @@
|
|||
---
|
||||
layout: page
|
||||
title: Getting started with the 1DS SDK (Beta) for Linux (C++)
|
||||
sub_title:
|
||||
|
||||
---
|
||||
This tutorial guides you through the process of integrating the 1DS SDK (Beta) into your existing C++ Windows app or service.
|
||||
|
||||
## **Clone the repository**
|
||||
|
||||
1. Run `git clone https://msasg.visualstudio.com/DefaultCollection/Shared%20Data/_git/Aria.SDK.Cpp` to clone the repo.
|
||||
|
||||
2. You will be asked your credentials to clone the repo, use your username and password as entered on https://msasg.visualstudio.com/DefaultCollection/_usersSettings/altcreds
|
||||
|
||||
If you do not have those credentials, generate them and use the username and password that you enabled.
|
||||
|
||||
## **Windows prerequisites and dependencies for building from source using Visual Studio 2017**
|
||||
|
||||
* Visual Studio 2017
|
||||
* C++ Dev Tools for Visual Studio 2017
|
||||
|
||||
## **Build the SDK from source using Visual Studio 2017**
|
||||
|
||||
* Navigate to the folder where the SDK was cloned and open the Aria.SDK.Cpp/Solutions folder
|
||||
|
||||
* Open the AriaSDK.sln file to open the project with Visual Studio 2017.
|
||||
|
||||
* Expand the Samples folder, the project HelloAria should be located there
|
||||
|
||||
|
||||
|
||||
* Go to the HelloAria project properties and make sure that Visual Studio 2017 is set as Platform Toolset
|
||||
|
||||
|
||||
|
||||
* When you build the HelloAria sample app Visual studio will also build the SDK, as it is listed as a dependency.
|
||||
The win32-dll project is the SDK dll, when Visual Studio builds it, it will also build all it's references, including sqlite, zlib and all the headers for the SDK to work.
|
||||
|
||||
|
||||
|
||||
## **Windows prerequisites and dependencies for building from source using LLVM compiler**
|
||||
|
||||
* LLVM compiler
|
||||
* CMake build system
|
||||
|
||||
### Install instructions
|
||||
|
||||
- Install CMake for Windows into C:\Program Files\CMake\bin\ (default path)
|
||||
- Install **[LLVM/clang for Windows](http://releases.llvm.org/7.0.0/LLVM-7.0.0-win64.exe)** and install into C:\Program Files\LLVM\bin (default path)
|
||||
|
||||
|
||||
## **Build the SDK from source using LLVM compiler**
|
||||
|
||||
1. Navigate to the directory where the SDK is located
|
||||
|
||||
2. Run the file `build-cmake-clang.sh` to build the SDK, this will build the SDK along with Unit and Functional Tests.
|
||||
|
||||
To disable building the tests go to the CMakeLists.txt file on the root of the SDK directory and change:
|
||||
|
||||
```
|
||||
option(BUILD_UNIT_TESTS "Build unit tests" YES)
|
||||
option(BUILD_FUNC_TESTS "Build functional tests" YES)
|
||||
```
|
||||
|
||||
to:
|
||||
```
|
||||
option(BUILD_UNIT_TESTS "Build unit tests" NO)
|
||||
option(BUILD_FUNC_TESTS "Build functional tests" NO)
|
||||
```
|
||||
|
||||
_**Note:** In order to build from scratch all dependencies along with the SDK you need to run:_ ` ./build-cmake-clang.sh clean`
|
||||
|
||||
_**Note:** If you want to skip building dependencies for the SDK you need to run:_ ` ./build-cmake-clang.sh nodeps`
|
||||
|
||||
3. The SDK will be installed under `<PATH>`
|
||||
|
||||
|
||||
|
||||
## **Instrument your code to send a telemetry event**
|
||||
|
||||
1. Include the main 1DS SDK (Beta) header file in your main.cpp by adding the following statement to the top of your app's implementation file.
|
||||
|
||||
```
|
||||
#include "LogManager.hpp"
|
||||
```
|
||||
|
||||
2. Introduce the 1DS SDK (Beta) namespace by adding the following statement after your include statements at the top of your app's implementation file.
|
||||
|
||||
```
|
||||
using namespace Microsoft::Applications::Events;
|
||||
```
|
||||
|
||||
3. Create the default LogManager instance for your project using the following macro in your main file:
|
||||
|
||||
```
|
||||
LOGMANAGER_INSTANCE
|
||||
```
|
||||
|
||||
4. Initialize the 1DS SDK (Beta) events system, create and send a telemetry event, and then flush the event queue and shut down the telemetry
|
||||
logging system by adding the following statements to your main() function.
|
||||
|
||||
```
|
||||
ILogger* logger = LogManager::Initialize("0123456789abcdef0123456789abcdef-01234567-0123-0123-0123-0123456789ab-0123");
|
||||
logger->LogEvent("My Telemetry Event");
|
||||
...
|
||||
LogManager::FlushAndTeardown();
|
||||
```
|
||||
_**Important!** Replace the place-holder application key value with the actual value of your application key._
|
||||
|
||||
*You're done! You can now compile and run your app, and it will send a telemetry event.*
|
||||
|
||||
_**Note:** If you need a deeper look into how to use the 1DS C++ SDK there is a couple of folders with examples under Aria.SDK.Cpp/examples_
|
||||
|
||||
|
||||
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 5.9 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 121 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 6.8 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 13 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 39 KiB |
|
|
@ -0,0 +1,4 @@
|
|||
[ViewState]
|
||||
Mode=
|
||||
Vid=
|
||||
FolderType=Pictures
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
layout: page
|
||||
title: Getting started with the 1DS SDK (Beta) for Linux (C++)
|
||||
sub_title:
|
||||
|
||||
---
|
||||
This tutorial guides you through the process of downloading and configuring Fiddler inspector on Mac OS X in order to see events sent with 1DS C++ Client SDK.
|
||||
|
||||
### **Installation instructions for 1DS Events protocol decoder / inspector for Fiddler**
|
||||
|
||||
1. Install latest Fiddler. Activate HTTPS traffic decoding. Follow the installer instructions on how to do this.
|
||||
|
||||
2. Copy the Fiddler inspector binary with latest CS3.0 protocol (with some CS4.0 fields) and bond protocol support located here:
|
||||
|
||||
**\\\\ARIA-BUILD-01.REDMOND.CORP.MICROSOFT.COM\\Releases\\Windows\\tools\\Fiddler\\OneDSInspector.zip**
|
||||
|
||||
to some directory of your choice.
|
||||
|
||||
3. Go to _**%LOCALAPPDATA%\Programs\fiddler-mac\Inspectors**_ and delete de v1 inspector if you have it. The v1 inspector uses an older version of the Bond lib and it will crash if you keep both versions in one directory. Delete the old inspector contents and deploy the contents of the copied .zip file (step 2) to _**%LOCALAPPDATA%\Programs\fiddler-mac\Inspectors**_.
|
||||
|
||||
4. Download Mono latest release for Mac OS X from the [official site](https://www.mono-project.com/download/stable/) and follow the installation instructions.
|
||||
|
||||
5. Follow Fiddler's guidelines ("Fiddler for OS X Install Instructions") available in the .zip archive from step 2.
|
||||
|
||||
_**Note:** You should follow those instructions in order to deploy moz certificates and ensure the SSL decryption works fine._
|
||||
|
||||
### **Running Fiddler on 32-bit mode and reading events**
|
||||
|
||||
1. To launch Fiddler on 32-bit mode you need to run: `mono --arch=32 Fiddler.exe`
|
||||
|
||||
2. After launching Fiddler on Mac go to Fiddler's proxy settings and make sure both options are checked: _**intercept SSL traffic**_ and _**Decrypt SSL traffic**_.
|
||||
|
||||
3. Make sure you click the [OK] button when enabling decryption.
|
||||
|
||||
_**Note:** Sometimes Mac OS X has some trouble rendering Fiddler's UI. If there's no [OK] Button showing up you might need to resize the window in order for it to appear._
|
||||
|
||||
For realtime monitoring of events flow, for one particular process (assuming the defaultp HTTP stack(libcurl) is not customized), the environment variable for libcurl must be set respect to the proxy you set when launching the process:
|
||||
|
||||
```
|
||||
export ALL_PROXY=127.0.0.1:8888
|
||||
./yourAppName.bin
|
||||
``
|
||||
|
||||
That would redirect all the HTTPS traffic via Fiddler.
|
||||
|
||||
|
||||
Now the events should be decrypted and formated to JSON when clicked on Fiddler:
|
||||
|
||||
|
||||
Загрузка…
Ссылка в новой задаче