Телеметрия в PowerShell: променливи, поверителност и предаване на данни

Ако работите с PowerShell ежедневно и започнете да чувате за Телеметрия в скриптове и сесииНормално е да имате въпроси: какви данни се изпращат, къде отиват, как да ги деактивирате или дори как сами да използвате тази телеметрия за отстраняване на грешки или наблюдение на собствените си скриптове. Всичко това става още по-важно, когато работите с корпоративна среда или чувствителна информация.

В следващите редове ще видите, подробно и на възможно най-простия език, Как работи телеметрията, свързана с PowerShell?Каква роля играят променливите на средата, как можете да се откажете, как ръчно да изпращате телеметрия (например до Application Insights) с помощта на PowerShell или curl и какви типични проблеми с мрежата, TLS или удостоверяването могат да доведат до липса на данни от вашите табла за управление.

Каква телеметрия изпраща PowerShell директно?

PowerShell, в съвременните си версии, включва собствен механизъм за изпращане на основни данни за употреба до Microsoft чрез Application Insights. Не говорим за кода, който пишете, а за самия PowerShell енджин, когато двоичният файл се изпълнява. pwsh.

Тази телеметрия помага на Microsoft да по-добре да разберете как да използвате PowerShell (версии, платформи, модули и др.) и приоритизиране на нови функции или корекции на грешки. Преди да бъде изпратена, информацията е анонимизира и добавя така че потребителят да не бъде директно идентифициран.

Има два ключови момента, в които се събират данни: в началото на сесията y периодично по време на изпълнениеВажно е да разберете това поведение, ако искате да имате максимален контрол върху това, което се споделя от вашата среда.

Освен това, моторът изпраща тази телеметрия само когато стартирате pwsh стандартен; ако PowerShell е вграден като двигател в друго хост приложениеТази първоначална телеметрия не се генерира.

Данните се изпращат при стартиране на pwsh

Когато сесията започне с pwshДвигателят събира малък, но много специфичен набор от информация за околната среда, която се изпраща само веднъж на ботушМежду другото, са записани следните: операционна система и подробности за инсталирането от PowerShell.

Този начален етап включва данни като производител, име и версия на операционната система на платформата, както и конкретната версия на PowerShell, която използвате в момента, което помага да се разбере комбинацията от системи, на които се използва.

Друга ключова информация, която се изпраща, е стойността на променлива на средата POWERSHELL_DISTRIBUTION_CHANNELТова показва канала, през който е инсталиран PowerShell (напр. официален пакет, хранилище и др.). Тази стойност се задава от инсталаторите и на потребителите се препоръчва да не я променят, за да избегнат изкривяване на показателите.

Включено е също Версия на SDK за Application Insights използван от самия PowerShell, приблизителната географска област на хоста въз основа на IP адреса, параметри, предадени на pwsh без техните ценности (т.е. имена на параметри, но не и съдържание) и ефективната политика за изпълнение на началната сесия.

Накрая, двигателят генерира два анонимни идентификатора: един Случаен GUID на потребител и други GUID на сесияТова не са директни лични данни, а технически идентификатори за групиране на сесии и поведения, без да се разкрива истинска самоличност.

Телеметрия, изпратена по време на сесията

След като сесията е в ход, PowerShell периодично изпраща обобщена информация за употребата, за да разбере какви функции се използват и какТова се отнася както за интерактивната конзола, така и за другите хостове, на които работи двигателят.

Тези данни включват, например, брой извиквания на API PowerShell.Create(), списъкът с импортирани модули на Microsoft заедно с техните версии или броят на модулите, които носят етикета CrescendoBuiltкоето помага да се идентифицира употребата на определени инструменти.

Съобщава се също следното: имената на включените и изключените експериментални функцииТова е много полезно, за да се разбере кои експерименти общността действително има в производство; освен това се изпраща стойността на предпочитанията. $PSNativeCommandUseErrorActionPreference (true, false или не е зададено) и броят на отворените отдалечени сесии.

Друга интересна част е каталогът на регистрирани подсистемиPowerShell показва имената, използвани за подсистемите за автоматично довършване (Completion) или общо (general), но ако името не е в този списък, то се изпраща като anonymous за да се запази поверителността.

Накрая, броячите са включени предложения, генерирани от CommandNotFound и статистика за употреба PowerShellUnsafeAssemblyLoad (включително дали зареждането е завършено успешно или не), ключови аспекти за подобряване на диагностиката и безопасността.

Как да деактивирате собствената телеметрия на PowerShell

Ако вашата организация има строги политики за поверителност, можете да укажете, че не искате тази телеметрия да се изпраща. PowerShell прави това, като предоставя променливата на средата. POWERSHELL_TELEMETRY_OPTOUT, което трябва да зададете преди да започнете каквато и да е сесия.

Разпознатата стойност за деактивиране на телеметрията може да бъде true, yes o 1Всеки от тези варианти казва на двигателя да не изпраща данни за употреба до Microsoft от този процес или от дъщерни процеси, които наследяват средата.

Важно е да се разбере, че тази конфигурация е базирана на Променливи на средатаСледователно, ако искате да бъде постоянен, трябва да го дефинирате в съответния обхват (потребител, машина или стартови скриптове) преди стартирането на PowerShell, а не след това.

Ако имате въпроси относно управлението на тези променливи, вижте самата документация на about_Environment_Variables и ръководството за променливи на средата на PowerShell ви помага да изберете правилния подход в зависимост от операционната система.

Също така не забравяйте, че инсталационните пакети, които разпространяват PowerShell, автоматично конфигурират POWERSHELL_DISTRIBUTION_CHANNEL за да се разграничи инсталационният канал. Тази променлива също е включена в телеметрията, така че не трябва да се манипулира ръчно.

Ключови променливи на средата, които влияят на PowerShell

PowerShell третира променливите на средата като специален тип данни, винаги във формата наследяеми текстови низове от дъщерни процесиТова ги прави идеални за контролиране на глобални опции като поверителност, актуализации или пътища на модули.

Самият двигател определя серия от специфични променливи, сред които се открояват следните: POWERSHELL_TELEMETRY_OPTOUT, POWERSHELL_DISTRIBUTION_CHANNEL, POWERSHELL_UPDATECHECK, PSExecutionPolicyPreference, PSModulePath, PSModuleAnalysisCachePath y PSDisableModuleAnalysisCacheCleanup.

En WindowsТези променливи могат да съществуват в обхват на машина (система), потребител или процесТекущият процес автоматично комбинира машинни и потребителски дефиниции и всички промени, които правите в сесия, засягат само този процес, освен ако не ги направите постоянни по друг начин.

За да промените стойности на ниво машина или потребител от PowerShell, ще трябва да използвате .NET клас System.Environment, който предоставя методи за четене и запис на променливи в тези области, при условие че имате достатъчно разрешения за това.

Имайте предвид, че тъй като са низове, променливите на средата могат да бъде обединено, изпразнено или премахнато доста лесно, което е много полезно за сложни конфигурационни скриптове или автоматизация на внедряването.

Начини за достъп и промяна на променливи на средата в PowerShell

PowerShell предлага няколко начина за заявки и промяна на променливи на средатаВ зависимост от това какво правите (писменост (бърз, сложен модул, административна задача) ще ви е интересно да използвате единия или другия.

Най-прекият начин е синтаксис на променливата с префикса $Env:което ви позволява да прочетете стойността на променлива или да ѝ присвоите нова стойност, сякаш е всяка друга променлива на PowerShell, например $Env:windir o $Env:Foo = "Algo".

Освен това, можете да използвате доставчик на среда (Env:) със стандартните командлети от елементи (Get-Item, New-Item, Set-Item, Remove-Itemи др.), което дава много последователен подход към обработката на единиците на файловата система.

В сценарии, където искате да работите на машинно или потребителско ниво или да интегрирате с .NET код, имате методите [Environment]::GetEnvironmentVariable() y [Environment]::SetEnvironmentVariable()Тези методи ви позволяват изрично да изберете обхвата (Process, User o Machine) в Windows системи.

От PowerShell 7.5 насам има и специфично поведение: можете задайте променлива на празен низ или на $null за да го изпразните или премахнете от сесията, използвайки синтаксиса $Env: като чрез Set-Item или методите на System.Environment.

Променливи на средата на PowerShell, свързани с телеметрията и поведението

Няколко вътрешни функции на PowerShell зависят от променливи на средата, които действат като наследяеми флагове за предпочитанияТова ви позволява да настройвате поведението на обвивката или телеметрията, без да се налага да променяте код във всеки скрипт.

Най-очевидният е POWERSHELL_TELEMETRY_OPTOUTкоето, както вече видяхме, служи за деактивиране на собствената телеметрия на двигателя, когато е настроено на true, yes o 1За да влезе това в сила, то трябва да съществува преди стартиране на процеса PowerShell.

Друго много важно е POWERSHELL_DISTRIBUTION_CHANNELТова поле, което инсталаторите попълват автоматично от PowerShell 7.2 насам, за да посочат как е инсталиран продуктът, е включено в телеметричните данни, така че не се препоръчва ръчна промяна.

променлив POWERSHELL_UPDATECHECK Контролира как и кога се показват известия за актуализации. Приема стойности като Off За да деактивирате функцията, Default за стандартно поведение или LTS да получавате известия само за версии с разширена поддръжка.

Освен това, PSExecutionPolicyPreference отразява активната политика за изпълнение в текущата сесия, когато е конфигурирана с помощта на параметъра -ExecutionPolicy, командата Set-ExecutionPolicy с обхват Processили чрез директно редактиране на променливата. Тази настройка засяга особено изтеглени или неподписани скриптове в Windows.

И, разбира се, пътят за търсене на модула се контролира с PSModulePath, който съхранява списък, разделен с точка и запетая в Windows или списък, разделен с двоеточие на *nix платформи, като външни инсталатори добавят както системни, така и потребителски местоположения и дори пътища.

Анализ на кеша и модулите: фина настройка

PowerShell поддържа кеш за анализ на модули за ускоряване на търсенията команди и да се избегне необходимостта от постоянна проверка на всички налични модули при всяко стартиране или търсене.

Променливата entorno PSModuleAnalysisCachePath Определете къде се съхранява този кеш файл. По подразбиране той сочи към пътища под $Env:LOCALAPPDATA на Windows или ~/.cache/powershell На системи, различни от Windows, с различно име на файл за всяка инсталация.

Ако искате да промените това местоположение, трябва да зададете тази променлива преди стартиране на PowerShellсочейки към пълен път (включително името на файла), където процесът има права за запис. Промените влизат в сила само за процеси, които стартират след промяната.

Ако целта ви е напълно да деактивирате кеширането на модули, можете да насочите пътя към дестинация, в която не може да се записва, например NUL на Windows или /dev/null en LinuxPowerShell ще се опита да запише кеша там, няма да успее, но също така няма да генерира видими грешки в сесията.

Допълва това променливата PSDisableModuleAnalysisCacheCleanupАко го настроите на 1Това деактивира автоматичното почистване, което премахва записи в модули, които вече не съществуват, което е полезно в специфични сценарии, където не искате да докосвате този кеш.

Други променливи на средата, полезни за скриптове и телеметрия

Освен специфичните за PowerShell, има набор от системни променливи на средата, които пряко влияят как се изпълняват скриптовете и как се държи системата терминалособено в мултиплатформени среди.

променлив PATH Това определя в кои директории да се търсят изпълними файлове, което е жизненоважно, ако ще стартирате външни двоични файлове от вашите PowerShell скриптове. В Windows директориите са разделени от... ;докато в Linux или macOS се използва :.

Windows също съществува PATHEXTТова изброява разширенията, които се считат за директно изпълними. Ако искате скриптов език да се изпълнява в същата конзола (например скриптови файлове), можете да използвате съответната команда. .py), ще трябва да включите разширението тук и да го регистрирате в системата, използвайки инструменти като assoc y ftype от CMD.

На платформи, различни от Windows, PowerShell се адаптира към XDG конвенцията, използвайки променливи XDG_CONFIG_HOME, XDG_DATA_HOME y XDG_CACHE_HOME за конфигурационни пътища, данни и кеш, което улеснява интеграцията с останалата част от системата.

За функциите за цветен изход и управлението на терминала, PowerShell 7.2 и по-нови версии спазват TERM y NO_COLORСпоред стойността на TERM ANSI последователностите са деактивирани или коригирани и ако има NO_COLORИзходният стил е принуден да бъде обикновен текст без цвят.

Дневник и резултатът от вашите скриптове Те влияят на това как изглеждат лог файловете и изходите на вашите скриптове, което се отразява както на конзолното изживяване, така и на четимостта на заснетото телеметрично съдържание, когато пренасочвате изхода към файлове.

Практически пример: Sophia Script и настройки за поверителност и телеметрия

Един от най-известните примери в общността за настройване на Windows 10 с PowerShell е Скриптът на София за Windows 10, набор от функции, насочени към автоматизиране на конфигурацията, поверителността и деинсталирането на ненужни компоненти.

Сред опциите си, Sophia Script включва възможността за регулиране на поверителността на системата и телеметрията, деактивиране на планирани диагностични задачи, деинсталиране на OneDrive, промяна на пътя на %TEMP% или преместете потребителски папки, като например Работен плот, Документи, DownloadsМузика, изображения или видеоклипове чрез интерактивни менюта.

Той предлага и функции за деинсталирайте UWP приложения за всички акаунти, спазващи списък с изключения, конфигурируеми чрез WPF формуляри, както и деактивиране на функции на Windows или премахване на системни възможности с визуални помощници.

Друга интересна част е, че може създаване на задачи в планировчика на задачи за периодично почистване, настройване на менюто „Старт“ (закачване или откачване на елементи), манипулиране на опциите за сигурност на Microsoft Defender, като например контролиран достъп до папки или изключения, и обновяване на икони, променливи на средата и лентата на задачите без рестартиране на Explorer.

Накратко, този тип скрипт демонстрира как, чрез комбиниране на PowerShell с телеметрични конфигурации, променливи на средата и автоматизация, може да се да моделира напълно поведението на Windows система да го адаптира към политиките на организацията или към личните предпочитания.

Изпращане на телеметрия от PowerShell към Application Insights

Освен вградената телеметрия на PowerShell, много приложения изпращат свои собствени данни за мониторинг до Azure Monitor Application InsightsПонякога обаче, когато отворите портала на Azure, диаграмите изглеждат празни или липсват ключови записи.

Типичните причини обикновено са грешки в конфигурацията на SDK или агента на Application Insights, мрежови блокажи към точка на поглъщане, ограничаване или изключване на телеметрията в конвейера, специфични инциденти на Log Analytics или проблеми със заявките към API api.applicationinsights.io.

Много практичен подход за изолиране на източника на проблема се състои от ръчно изпращане на единичен тестов телеметричен лог от PowerShell или curl. Ако този запис успешно достигне таблицата с регистрационни файлове на ресурса на Application Insights, знаете, че голяма част от конвейера работи.

Когато тествате от същата машина или среда, където се изпълнява приложението ви (например виртуалната машина или услугата за приложения), вие също така проверявате това DNS, защитна стена, TLS и разрешения не блокират пътя към поглъщане.

В сценарии, където точката на приемане е защитена с Microsoft Entra ID (преди Azure AD), трябва да се уверите, че приложението или скриптът се удостоверява правилно с Entra ID; в противен случай телеметрията ще бъде отхвърлена, дори ако останалата част от инструментариума изглежда правилна.

PowerShell скрипт за тестване на телеметрията за наличност

За да проверите дали цялата верига от вашата машина до Application Insights работи, можете да използвате PowerShell скрипт, който изпраща резултат от тест за наличностТози тип телеметрия е идеален, защото не е обект на механизмите за вземане на проби от всмукателния поток.

Идеята е проста: вие предоставяте верига за свързване или инструментален ключСкриптът го разделя, за да извлече точката на приемане и InstrumentationKey, генерира JSON с AvailabilityData като пример и го изпраща с Invoke-WebRequest към съответната REST крайна точка.

Ако подадете само инструменталния ключ, скриптът изгражда низ за свързване с глобална крайна точка https://dc.services.visualstudio.com/Ако предадете целия низ за свързване, ще се използва регионалната точка за приемане, дефинирана в него, а ако предадете и двете, ще има предимство тази, дефинирана в низа за свързване.

По време на изпълнението, a Времеви печат във формат UTC ISO 8601JSON тялото се попълва с тестовите данни (продължителност, местоположение, съобщение, допълнителни свойства) и се изпраща POST заявката. HTTP 200 отговорът с itemsReceived равен на itemsAccepted показва, че точката на прием е получила и приела записа.

След това просто отидете в раздела „Регистрационни файлове“ на ресурса Application Insights в портала Azure, изпълнете заявка за съответния тип и проверете дали се показва примерният лог. Ако се появи, знаете, че проблемът най-вероятно е в SDK или агент, който вашето реално приложение използва.

Тествайте телеметрията с curl на Linux или Windows

Ако средата, от която искате да тествате, е Linux или macOS, или ако предпочитате да използвате стандартни инструменти вместо PowerShell, можете да извършите същия тест с curl изпраща POST заявка с JSON съдържание към крайната точка на Application Insights.

В тези случаи създавате подобно JSON тяло, с baseType равен на AvailabilityDataИдентификатор на изпълнение, име на теста, продължителност, индикатор за успех, местоположение, съобщение и допълнителни свойства. Не забравяйте винаги да коригирате Кампо time към скорошна марказащото Application Insights приема данни, по-стари от 48 часа.

За Linux или macOS командата обикновено включва глава Content-Type: application/json, POST методът, вграденият JSON и URL адресът на точката за приемане (например https://dc.applicationinsights.azure.com/v2.1/track). В Windows синтаксисът се променя леко, защото трябва да се избягват кавички в JSON файла, когато се предава като аргумент.

След като това е направено, проверявате отново HTTP отговора и ако е правилен, отивате в регистрационните файлове на Application Insights, за да потвърдите, че тестовата ви телеметрия вече е съхранена и може да бъде заявена, точно както беше със скрипта PowerShell.

Този подход ви позволява да изключите проблеми с конфигурацията на SDK с един поглед, като се фокусирате върху мрежови, DNS, TLS, удостоверяване на крайни точки или правила за вземане на проби въз основа на симптомите, които виждате в отговора.

PowerShell скрипт за тестване на телеметрията на заявките

В допълнение към тестовете за наличност, често се интересувате от проверка на Телеметрия на HTTP заявкиособено когато вашите табла за управление са базирани на показатели за входящи заявки от API или уеб приложение.

За да направите това, можете да използвате друг PowerShell скрипт, много подобен на този за наличност, но този път генериращ JSON с baseType равен на RequestDataОбикновено се включват полета като идентификатора на заявката и името на операцията (например). GET /ruta/prueba/), началното време, продължителността, URL адреса, кода на отговора и HTTP метода.

Скриптът следва същата механика: той разделя низа за свързване или инструменталния ключ, конструира URL адреса за приемане (v2/track), изчислява текущото време в UTC, асемблира JSON и изпълнява Invoke-WebRequest използвайки POST методаАко получите код 200 и очакваното съдържание в отговора, частта за приемане работи.

Ето един важен момент: приложенията наистина могат да бъдат засегнати от механизми за вземане на проби От страна на сървъра. Ако сте конфигурирали семплиране, за да намалите обема на данните, може да не виждате всички заявки за тестване, освен ако временно не го деактивирате или не коригирате процентите.

След като тестовият ви лог се появи в Application Insights, следващата стъпка е да се съсредоточите върху това как е инструментализиран вашият код (SDK, филтри, семплиране, изключения и др.), за да разберете защо реалните заявки не се регистрират толкова лесно, колкото ръчните тестове.

Често срещани проблеми с SSL/TLS при изпращане на телеметрия

Не е необичайно да се сблъскате с грешки, свързани с изпълнението на тези тестови скриптове. SSL или TLS по време на ръкостисканеособено в ограничени среди или когато корпоративни прокси сървъри проверяват трафика.

Много услуги на Azure, включително Application Insights, изискват поне TLS 1.2 и специфични шифри за приемане на връзки. Ако системата или приложението продължи да използва TLS 1.0 или 1.1 по подразбиране, връзката може да се провали дори преди сървърът да обработи JSON.

PowerShell ви позволява да наложите поддържани протоколи, като зададете [System.Net.ServicePointManager]::SecurityProtocol преди изпълнение Invoke-WebRequestМожете да опитате SSL3, TLS, TLS 1.1, TLS 1.2 или TLS 1.3, за да видите какво работи във вашата среда, въпреки че в производствения режим се препоръчва да се придържате към указанията за сигурност.

Ако имате и прокси сървъри или защитни стени, извършващи SSL проверка, валидирането на сертификата може да се провали. Има опция за деактивиране на проверката на сертификата създаване на персонализирана политика, която винаги връща true, но това е нещо, което трябва да използвате само за диагностика и никога като постоянно решение.

Когато трябва да промените версиите на TLS по подразбиране, използвани от .NET приложенията в Windows, правилната процедура е да следвате следните стъпки: Официални препоръки за конфигурация на TLS в системния регистър и в самата рамка, вместо да се въвеждат разпръснати хакове в скриптовете.

Грешки при удостоверяване с Microsoft. Въведете ID в Application Insights.

Ако вашият ресурс Application Insights е конфигуриран да приема само Удостоверяване с помощта на Microsoft Enter ID (преди Azure AD), телеметрията, изпратена с инструментален ключ без валидни идентификационни данни, ще бъде отхвърлена с ясни HTTP грешки.

Код HTTP 400 със съобщение, показващо, че класическото удостоверяване не се поддържа Това обикновено означава, че ресурсът е маркиран само като Entra ID, но SDK или скриптът извиква стария API. В този случай трябва да проверите конфигурацията на SDK и използвания низ за свързване.

Грешка HTTP 401 „Изисква се оторизация“ Това предполага, че SDK се опитва да използва Entra ID, но не може да получи валиден токен; това може да се дължи на факта, че управляваната самоличност не е активирана, липсват идентификационни данни или проблеми с Azure Identity на клиента.

Кодът HTTP 403 „Неоторизирано“ Това показва, че е получен токен, но използваната самоличност няма достатъчни разрешения за ресурса на Application Insights или абонамента. В този случай трябва да прегледате контрола на достъпа и да се уверите, че самоличността има поне ролята „Издател на показатели за наблюдение“.

В зависимост от езика (Node.js, Питони др.), препоръчително е да активирате вътрешни SDK лог файлове или регистрационните файлове на Azure Identity, за да видите точно кой етап от удостоверяването е неуспешен и с какво съобщение.

Телеметрия, скриптове и най-добри практики в реални среди

Всичко гореизброено означава, че когато искате Добавяне на телеметрия към скриптове в PowerShellИмате две нива за управление: от една страна, автоматичната телеметрия на самия енджин, а от друга страна, изричната телеметрия, която изпращате към системи като Application Insights или други дестинации.

На местно ниво е ключово да се знае как работи POWERSHELL_ТЕЛЕМЕТРИЯ_ИЗКЛЮЧВАНЕ, какви данни се събират в началото и по време на сесията и как променливи като POWERSHELL_DISTRIBUTION_CHANNEL o POWERSHELL_UPDATECHECK да контролира глобалното поведение.

По отношение на вашите скриптове, можете да се възползвате от променливите на средата, доставчика Env:, методите на System.Environment и инструменти като Sophia Script за Настройте правилата за поверителност, маршрути, кеш и изпълнение, докато внедрявате процесите си за изпращане на показатели и регистрационни файлове до външни услуги.

Чрез комбиниране на ръчно телеметрично тестване с PowerShell и Curl, наблюдение на TLS протоколи и правилно конфигуриране на удостоверяване с Microsoft Entra ID, е възможно да се постигне... стабилен и надежден телеметричен тръбопровод дори в силно контролирани корпоративни среди.

Когато разберете как е организиран целият този телеметричен слой, от променливите на околната среда до приемането на данни в облака, става много по-лесно да вземете решение. кои лостове да натисна Ако един ден вашите графики или регистрационни файлове в Azure мистериозно спрат да се актуализират.